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Customer Satisfaction 

If you discover physical defects in the manuals distributed with a Lisa 
product or in the media on which a software product is distributed^ Apple 
will replace the documentation or media at no charge to you during the 
90-day period after you purchased the product. 



Product Revisions 

Unless you have purchased the product update service available through 
your authorized Lisa dealer, Apple cannot guarantee that you will receive 
notice of a revision to the software described in this manual, even if you 
have returned a registration card received with the product. You should 
check periodically with your authorized Lisa dealer. 



Limitation on Warranties and Liability 

All implied warranties concerning this manual and media, including implied 
warranties of merchantability and fitness for a particular purpose, are 
limited in duration to ninety (90) days from the date of original retail 
purchase of this product 

Even though Apple has tested the software described in this manual and 
reviewed its contents, neither Apple nor its software suppliers make any 
warranty or representation, either express or implied, with respect to this 
manual or to the software described in this manual, their quality, 
performance, merchantability, or fitness for any particular purpose. As a 
result, this software and manual are sold "as is," and you the purchaser are 
assuming the entire risk as to their quality and performance. 

In no event will Apple or its software suppliers be liable for direct, 
indirect, special, incidental, or consequential damages resulting from any 
defect in the software or manual, even if they have been advised of the 
possibility of such damages. In particular, they shall have no liability for 
any programs or data stored in or used with Apple products, including the 
costs of recovering or reproducing these programs or data 

The warranty and remedies set forth above are exclusive and in lieu of all 
others, oral or written, express or implied. No Apple dealer^ agent or 
employee is authorized to make any modification, extension or addition to 
this warranty. 

Some states do not allow the exclusion or limitation of implied warranties 
or liability for incidental or consequential damages, so the above limitation 
or exclusion may not apply to you. This warranty gives you specific legal 
rights, and you may also have other rights that vary from state to state. 
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License and Copyrl^t 

This manual and the software (computer programs) described in it are 
copyrighted by Apple or by Apple's software suppliers^ with all rights 
reserved, and they are covered by the Lisa Software License Agreement 
signed by each Lisa owner. Under the copyright laws and the License 
Agreement, this manual or the programs may not be copied, in whole or in 
part, without the written consent of Apple, except in the normal use of 
the software or to make a backup copy. This exception does not allow 
copies to be made for others, whether or not sold, but all of the material 
purchased (with all backup copies) may be sold, given, or loaned to other 
persons if they agree to be bound by the provisions of the License 
Agreement. Copying includes translating into another language or format. 

You may use the software on any computer owned by you, but extra copies 
cannot be made for this purpose. For some products, a multiuse license 
may be purchased to allow the software to be used on more than one 
computer owned by the purchaser, including a shared-disk system. 
(Contact your authorized Lisa dealer for more information on multiuse 
licenses.) 



Product Revisions 

Unless you have purchased the product update service available through 
your authorized Lisa dealer, Apple cannot guarantee that you will receive 
notice of a revision to the software described in this manual, even if you 
have returned a registration card received with the product You should 
check periodically with your authorized Lisa dealer. 
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Preface 



The Contents of TTds Manual 

This manual describes the Operating System service calls that are available to 
Pascal and assembler programs. It is written for experienced Pascal 
programmers and does not explain elementary terms and programming 
techniques, we assume that you have read the Lisa Owner's Guide and 
Workshop User's Guide for the Lisa and are familiar with your Lisa system. 

Chapter i is a general introduction to the operating system. 

Chapter 2 describes the File System and the available File System calls. This 
includes a description of the interprocess communication facility, pipes, and 
the Operating System calls that allow processes to use pipes. 

Chapter 3 describes the calls available to control processes, and also describes 
the structure of processes. 

Chapter ft describes how processes can control their use of available memory. 

Chapter 5 describes the use of events and exceptions that control process 
synchronization, it also describes the use of the system clock. 

Chapter 6 describes the calls you can use to find out about the configuration 
of the system. 

Appendix A contains the source text of syscall, the unit that contains the 
type, procedure, and function definitions discussed in this manual. 

Appendix B contains a list of system-reserved exception names. 

Appendix c contains a list of system-reserved event names. 

Appendix D contains a list of error messages that can be produced by the 
calls documented in this manual. 

Appendix E contains a description of the information you can obtain from the 
operating System about files and devices. 

Type and Syntax Conventions 

Bold-face type is used in this manual to distinguish programming keywords and 
constructs from English text. For example, FLUSH is the name of a system 
can. System call names are capitalized in this manual, although Pascal does 
not distinguish between lower and upper case characters. Italics indicate a 
new term whose explanation follows. 
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Future Releases 

A few features of the Lisa Operating System will be changed In future 
releases: 

• Pipes will not be supported. 

• Timed events will not be supported 

• Configuration System Calls will be changed. 

If you want your software to be upward-compatible^ please take these changes 
Into consideration. More information Is provided In the appropriate sections 
of the manual. 
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Introduction 



The Operating System (OS) provldej an environment in which multiple processes 
can coexist, communicate, and share data It provides a file system for I/O 
and information storage, handles exceptions (software interrupts), and perfomns 
memory management 

1.1 lYie Main Functions 

This chapter describes the four main functional areas of the OS: the File 
System, process management, memory management, and event and exception 
handling. 

The File System provides input and output. The File System accesses devices, 
volumes, and files. Each object, whether a printer, disk file, or any other type 
of object, is referenced by a pathname. Every I/O operation is performed as 
an uninterpreted byte stream. Using the File System, all I/O is device 
independent. The File System also provides device-specific control operations. 

A process consists of an executing program and its associated data Several 
processes can execute concurrently by multiplexing the processor between 
them. These processes can be broken into segments which are automatically 
swapped into memory as needed. 

Memory management routines handle data segments. A data segment is a file 
that can be placed in memory and accessed directly. 

Exceptions and events are process-communication constructs provided by the 
OS. An event is a message sent from one process to another, or from a 
process to itself, that is delivered to the receiving process only when the 
process asks for that event An exception is a special type of event that 
forces Itself on the receiving process. There is a set of system-'defined 
exceptions (errors), and programs can define their own. System errors such as 
division tiy zero are examples of system-defined exceptions. You can use the 
system calls provided to define any exceptions you want 

12 Using the OS Functions 

Both built-in language features and explicit OS system calls can access OS 
routines to perform desired functions. For example, the Pascal writein 
procedure Is a built-in feature of the language. The code to execute wilteln 
is supplied in lOSPASLIB, the Pascal run-time support routines llbraa-y. This 
code, which is added to the program when the program Is linked/ calls OS 
File System routines to perform the desired output 

You can also call OS routines explicitly. This Is usually done when the 
language does not provide the operation you want OS routines allow Pascal 
programs, for example, to create new processes, which could not otherwise be 
done, since Pascal does not have any built-in process^handllng functions. 
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All calls to the OS are synchronous, which means they do not return until the 
operation is complete. Each call returns an error code to indicate if anything 
went wrong during the operatioa Any non-zero value indicates an error or 
warning. Negative error codes indicate warnings. For a list of error codes 
and their meaning, see Appendix D. 

13 The File System 

The File System performs all I/O as uninterpreted byte streams. These dyte 
streams can go to files on disk or to other devices such as a printer or an 
alternative console. In all cases, the device or file has a File System name. 
Except for device-control functions, the File System treats devices and files 
in the same way. 

The File System allows sharing of all types of objects. 

The File System provides for naming objects (devices, files, etc.). A name in 
the File System is called a pathname A complete pathname consists of a 
directory name and a file name. The file name is meaningful only for storage 
devices (devices that store byte streams for later use, such as disksX 

Each process has a working directory associated with it. This allows you to 
reference objects with an incomplete pathname. To access an object in the 
working directory, you specify its file name. To access an object In a 
different directory, you specify its complete pathname. 

Before a device can be accessed, it must be mounted. Devices can be 
mounted using the Preferences tool or by using the MOUNT call. See Chapter 
2 for an explanation of this call and other File System calls. If the device is 
a storage device, the mount operation makes a wJume name available. A 
volume name is a logical name for a disk, and is saved on the disk itself. The 
mount operation logically connects the volume to the system^ so that the files 
on the volume may be accessed. The volume name can replace a device name 
in a pathname used to access an object on the disk. The volume name allows 
you to access a file with the same pathname no matter where the drive is 
actually connected. 

A device can be accessed if it is specified in the configuration list created by 
the Preferences tool, is physically connected to the Lisa, and is mounted. 
There are some operations that can be performed on unmounted devices. Two 
examples are DEYICEJCXMTROL calls and scavenging. Logically mounting a 
volume on a device makes file access to the volume possible. For storage 
devices, a volume is an actual magnetic medium that can contain recorded 
files. For non-storage devices, volumes and files are concepts used to 
nnalntain a uniform interface. Flies on non-storage devices such as printers 
do not store data but act as ports for performing I/O to the devices. 
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The basic operations provided by the File System are as follows: 

nnount and unmount - make a volume accessible/Inaccessible 
open and close - make an object accessible/Inaccessible 
read and write - transfer Information to and from an object 
device control functions - control device-specific functions 

Some operations apply only to storage devices: 

allocate and deallocate - specify size of an object 

manipulate catalog - control naming of objects and creation and 

destruction of objects 
manipulate attributes - look at or change the characteristics of 

the object 

In addition to the data in an object^ the object itself has certain 
characteristics called attrltxttesi such as the length and creation date of a 
file. Calls are available to access the attributes of any File System object. In 
addition to its system-defined attributes^ an object on a storage device can 
have a label The label is available for programs to store information that 
they can interpret 

Non-storage devices such as printers are accessed with a limited set of 
operations. They must be mounted and opened before they can be accessed. 
Sequential read and/or write operations are available as appropriate for the 
device. Device-control functions are available to perform any device- 
specific functions needed. The file-name portion of the complete pathname 
for a non-storage device Is not used by the File System^ although you do have 
to provide one when you open the device. 

For storage devices^ the same sequential read and write operations are valid 
as for non-storage devices. Storage devices also must be mounted^ and 
particular files opened^ before the files can be used. They have appropriate 
device-control functions avallabla 

When writing to a disk file, space for the file is allocated as needed. Space 
for a file does not need to be contiguous, and in some cases this automatic 
allocation can result in a fragmented file, which may slow file access. To 
insure rapid access, you can pre-allocate space for the fll& Pre-allocating 
the file also ensures that the process will not run out of space on the disk. 

Four types of objects can be stored on storage devices. These are files, pipes, 
data segments, and event channels. Files, already discussed, are simply arrays 
of stored data Pipes are objects that provide Interprocess communicatloa 
Data segments are special cases of files that are loaded into memory along 
with program code. Event channels are pipes with a specialized structure 
Imposed by the system. 

L4 Process Management 

A process is an executing program and the data associated with it. Several 
processes can exist at one time, and they appear to run simultaneously 
because the CPU is multiplexed among them. The Scheduler decides what 
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process should use the CPU at any one lime, it uses a generally non- 
preemptive scheduling algorithm. This means that a process will not lose the 
CPU unless It blocks. The DlocKed state Is e)q3lalned later In this section. 

A process can lose the CPU when one of the following happens: 

• The process calls an operating System procedure or function. 

• The process references one of Its code segments that Is not currently in 
memory. 

If neither of these occur^ the process will not lose the CPU. 

Every process is started by another process. The newly started process is 
called the son process, The process that started it is called its father process 
The resulting structure is a tree of processes. See Figure 3-2 for an 
illustration of a process tree. 

When any process terminates^ all its son processes and their descendants are 
also terminated. 

When the OS is booted, it starts a shell process The shell process starts any 
other processes desired by the user. 

Every newly created process has the same system-standard attributes and 
capabilities. These can be changed by using system calls. 

Any processes can suspend^ activate^ or kill any other process for which the 
global ID is known, as long as the other process does not protect itself. 

The memory accesses of an executing process are restricted to its own 
memory address space. Processes can communicate with other processes Xi'i 
using shared fiies^ pipes, event channels, or shared data segments. 

A process can be in one of three states: ready, running, or blocked. A reaav 
process i% waiting for the Scheduler to select it to run. A running pwcess\% 
currently using the CPU to execute Its code. A mocked process\% waiting for 
some event, such as the completion of an I/O operation. It will not be 
scheduled until the event occurs, at which point it becomes ready. A 
teimlnated process\\&i finished executing. 

Each process has a priority from l to 255. The higher the number, the higher 
the priority of the process. Priorities 226 to 255 are reserved for system 
processes. The Scheduler always runs the ready process with the highest 
priority. A process can change its own priority, or the priority of any other 
process, while It is executing. 

IS Memory Management 

Memory managment is concerned with what is in physical memory at any one 
time. Each process can use up to 128 memory segments. Each segment can 
contain up to 128 Kbytes. Memory segments are of two types: code segments 
and data segments. The total amount of memory used by any one process can 
exceed the available RAM of the Lisa The Operating System will swap code 
segments in and out of memory as they are needed. To aid the Operating 
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System in swapping data segments^ calls are provided to give programs the 
ability to define which data segments must be in memory while a particular 
part of the program is executing. 

You have control of how your program is divided up. For executable code 
segments^ you use the segmentation commands of the Pascal compiler to break 
the program in pieces. 

In addition to residing in memory^ data segments can be stored permanently 
on disk. They can be accessed with calls similar to File System calls. This 
allows you to use a data segment as a direct-access file—a file that is 
accessed as part of your memory space. 

Calls are provided for making, killing, opening, and closing data segments. 
You can also change the size of a data segment and set its access mode to 
read-only or read-write. In addition, you can make a permanent disk copy of 
the contents of a data segment at any time. Other calls give you ability to 
force the contents of the data segment to be swapped into main memory so 
they can be accessed by your process. 

1.6 Exceptions and Events 

An exception is an unexpected condition in the execution of a process (an 
interruptX An event Is a message from another process. 

An exception can be generated either by the system or by an executing 
program. System exceptions are generated by various sorts of errors such as 
divide by zero. Illegal Instruction, and Illegal address. System exception 
handlers are supplied that terminate the process. You can write your own 
exception handlers for any of these exceptions If you want to try to recover 
from the error. 

User exceptions can be declared and exception handlers can be written to 
process them. Your program can then signal this new exception. 

Events are messages sent from one process to another. They are sent through 
event channels. 

A process that expects a message from an event channel executes a call to 
wait for an event on that channel. This will give it the next message, if one 
exists, or block the process until a message anlves. 

If a process wants to know when an event arrives, but does not want to wait 
for It, It can use an event-call channel. This Is set up by associating a user 
exception with the event channel when it is opened. The Operating System 
will then Invoke the corresponding user exception handler whenever a message 
arrives In the event channel. 

1.7 mterprocess Communication 

There are four methods for Interprocess communication: shared files, pipes, 
event channels, and shared data segments. 
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Shared files are used for high voiunf» transfers of information. It Is necessary 
to coordinate the processes somehow to prevent them from overwriting each 
other's Information. 

Pipes are used for communication between processes with an uninterpreted 
byte stream. (Note that pipes will not be supported in future releases of the 
Operating System.) The pipe mechanism provides for the needed 
synchronization; a process will block if it is trying to read from an empty 
pipe or write to a full one, A read from a pipe consumes the information^ so 
it is no longer available. Only one process can read from a given pipe. 

Event channels are similar to pipes, except that event channels transmit short, 
structured messages Instead of uninterpreted bytes. 

A shared data segment can be used to transmit a large amount of data 
rapidly. Having a shared data segment means that this data segment is in the 
memory address space of all the processes that want to use it. All the 
processes can then directly read and write Information in the data segment. 
It is necessary to provide some sort of synchronization to keep one process 
from overwriting another's Information. 

1.8 Using the OS Interface 

The Interface to all the system calls is provided In the syscail unit found in 
Appendix A. This unit can be used to provide access to the calls. See the 
workshop User's Guide for trie Usa for more information on using Syscail. 

1.9 Running Programs under the 08 

Programs can be written and run by using the Workshop, which provides 
program development tools such as editing and debugging facilities. 

1.10 Writing Programs lT»t Use the OS 

You can write a program that calls OS routines to perform needed functions. 
This program uses the Syscdil unit and then calls the routines needed. 
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The File System provides device-independent I/O^ storage with access 
protection, and uniform file-naming conventions. 

Device independence means that all I/O is performed in the same way, 
whether the ultimate destination or source is disk storage, another program, a 
printer, or anything else, in all cases, I/O Is performed to or from flle^ 
although those files can also be devices, data segments, or programs. 

Every file is an uninterpreted stream of eight-bit bytes. 

A file that is stored on a block-structured device, such as a disk, is listed in 
a catalog {^\%Q called a director^ and has a name. For each such file the 
catalog contains an entry describing the file's attributes, including the length 
of the, file, its position on the disk, and the last backup copy date. Arbitrary 
application-defined information can be stored in an area called the flJe Jadei 
Each file has two associated measures of length, the Logical End of File 
(LEOF) and the Physical End of File (PEOF) The LEOF is a pointer to the last 
byte that has meaningful data. The PEOF is a count of the number of blocks 
allocated to the file. The pointer to the next byte to be read or written is 
called the file marker. 

Since I/O is device independent, application programs do not have to take 
account of the physical characteristics of a device. However, on block- 
structured devices, programs can make I/O requests in whole-block increments 
In order to improve program performance. 

All input and output is synchrorKWS in that the I/O requested is performed 
before the call returns. The actual l/Q, however, is asynchronous, in that 
processes may block when performing I/a See Section 3.5, Process Scheduling, 
for more information on blocking. 

To reduce the impact of an error, the File System maintains distributed, 
redundant information about the files on storage devices. Duplicate copies of 
erlttcal information are stored In differer^t forms and in different places on 
the media. All the files are able to identify and describe themselves, and 
there are usually several ways to recover lost information. The Scavenger 
utility is able to reconstruct damapd catalogs from the information stored 
with each file. 

2.1 FUt Names 

All the files known to the operating System at a particular time are organized 
Into catalogs. Each disk volume has a catalog that lists all the files on the 
disk. 

Any object catalogued in the File System can be named by specifying the 
volume on which the file resides and the file name. The mmes are separated 
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by the character •*-". Because the top catalog In the system has no name^ all 
complete pathnames begin with "-". 

For example^ 

-LISA-FORMAT.TEXT 

refers to a file named FORMAT. TEXT on a volume named LISA. The file 
name can contain up to 32 characters. If a longer name is specified^ the 
name is truncated to 32 characten. Accesses to sequential devices use an 
arbitrary dummy filename that is ignored Out must be present in the 
pathname. For example^ the serial port pathname 

-RS232B 

is insufficient^ but 

-RS232B-XYZ 

is accepted^ even though the -XYZ portion is Ignored. Certain device names 
are predefined: 

RS232A Serial Port A 

RS232B serial Port B 

PARAPORT Parallel Port 

SLOTxCHANy Serial ports: x is 1^ 2^ or 3 and y is l or 2 

riAlNCON»)LE wrlteln and readln device 

ALTCONSOLE writeln and readln device 

UPPER Upper Diskette drive (Drive i) 

LOWER Lower Diskette drive (Drive 2) 

BITBKT Bit ducket: data is thrown away when directed here 

See Chapter 6 for more information on device names. 

upper and lower case are not significant in pathnames: 'TESTVOL* is the same 
object as 'TestVol*. Any ASCII character is legal in a pathname. Including 
non-printing characters and blank spaces. However, use of ASCII 13, 
RETURN, In a pathname Is strongly discouraged. 

2.2 The working Directory 

It is sometimes inconvenient to specify a complete pathname, especially when 
working with a group of files in the same volume. To alleviate this problem, 
the Operating System maintains the name of a working directory for each 
process. When a pathname is specified without a leading "-", the name refers 
to an object in the working directory. For example, if the working directory 
is -LISA the name FORMAT.TEXT refers to the same file as 
-LISA-FORMAT.TEXT. The default working directory name is the name of the 
boot volume directory. 

You can find out what the working directory is with QET_WORKING_DIR 
You can change to a new working directory with SET_WCPKING_DIR. 
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23 Devices 

Device names follow the same conventions as file names. Attributes like baud 
rate are controlled by using the DEVICEJDGNTROL call with the appropriate 
pathname. 

Each device has a permanently assigned priority. From highest to lowest^ the 
priorities are: 

Power on/off button 

serial port A (RS232A) 

Serial port B (RS232B, the leftnost port) 

I/O slot 1 

I/O slot 2 

I/O slot 3 

Keyboard^ mouse, battery-powered clock 

10 m system timer 

CRT vertical retrace interrupt 

Parallel port 

Diskette i (UPPER) 

Diskette 2 (LOWER) 

Video screen 

The device driver associated with a device contains information about the 
device's physical characteristics such as sector size and Interleave factors for 
disks. 

2.4 Storage Devices 

On storage devices such as disk drives, the File System reads or writes file 
data in terms of pages. A page\s the same size as a block. Any access to 
data In a file ultimately translates into one or more page accesses. When a 
program requests an amount of data that does not fit evenly into some 
number of pages, the File System reads the next highest number of whole 
pages. Similarly, data Is actually written to a file only In whole page 
Increments. 

A file does not need to occupy contiguous pages. The File System keeps 
track of the locations of all the pages that make up a file. 

Each page on a storage device Is self-ldentlfylng; the page descriptor \% stored 
with the page contents to reduce the destructive Impact of an I/O error. 

The eight components of the page descriptor are: 

Version number 

volume identifier 

File identifier 

Amount of data on the page 

Page name 

Page position in the file 

Forward link 

Backward link 
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Each volume has a Medium Descriptor Data Fiie (MODFJ^Mc^ descrlDes the 
various attributes of the rnedlum such as Its slze^ page lengthy block layout 
and the size of the boot area The MDDF is created when the volume is 
initialized. 

The File System also maintains a record of which pages on the medium are 
currently allocated^ and a catalog of all the files on the volume. Each file 
contains a set of file hints^ which describe and point to the actual file data 

2.5 The Volume Catalog 

On a storage device^ the volume catalog provides access to the files. The 
catalog is Itself a file that maps user names Into the internal file identifiers 
used by the Operating System. Each catalog entry contains a variety of 
Information about each file Including: 

Nafne 

Type 

Internal file number and address 

size 

Date and tine created, last modified, and last accessed 

File identifier 

Safety switch 

The safety switch is used to avoid accidental deletions. While the safety 
switch is on, the file cannot be deleted. The other fields are described under 
the LOOKUP File System call. 

The catalog can be located anywhere on the medium. 

2.6 Labels 

An application can store its own information about a file In an area called 
the fiie iabel The label allows an application to keep the file data separate 
from information maintained about the file. Labels can be used for any 
object in the File System. The maximum label size is 128 bytes. I/O to labels 
is handled separately from file data l/a 

2.7 Logical and Physical End of File 

A file contains some number of bytes of data recorded In some number of 
physical pages. Additional pages which do not contain any file data can be 
allocated to the file. There are, therefore, two measures of the end of the 
file. The Logical End of File (LEOF) is a pointer to the last stored byte that 
has meaning to the application. The Physical End of File (PEOF) is a count of 
the number of pages allocated to the file. 

in addition, each open file has a pointer called the Hie marker^M.^ points 
to the next byte In the file to be read or written. When the file Is opened, 
the file marker points to the first byte (byte number 0). The file marker can 
be positioned automatically or explicitly using the read and write calls. For 
example, when a program writes to a file opened with Append access, the file 
marker Is automatically positioned to the end of the file before new data are 
written. The file marker cannot be positioned past LEOF except by a write 
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operation that appends data to a file; in this case the file marker is 
positioned one byte past LECF. 

When a file is created^ an entry for it is made in the catalog specified In Its 
pathname, but no space is allocated for the file itself. When the file is 
opened by a process, space can be allocated explicitly by the process, or 
automatically by the Operating System. If a write operation causes the file 
marker to be positioned past the LEOF marker, LEOF (and PEOF if necessary) 
are automatically extended. The new space is contiguous if possibla 

2^ File Access 

The File System provides a device-independent bytestream interface. As far 
as an application program is concerned, a specified number of bytes is 
transferred either relative to the file marker or at a specified byte location 
in the file. The physical attributes of the device or file are not important to 
the application, except that devices that do not support positioning can 
perform only sequential operations. Programs can sometimes improve 
performance, however, by taking advantage of a device's physical 
characteristics. 

Programs can request any amount of data from a file. The actual 1/0, 
however. Is performed in whole-page Increments when devices are block 
structured. Therefore, programs can optimize I/O to such devices by setting 
the file marker on a page boundary and making I/O requests In whole-page 
Increments. 

A file can be open for access by more than one process concurrently. All 
requests to write to the file are completed before any other access to the file 
Is permitted. When one process writes to a file, the effect of the write 
operation Is Immediately available to all other processes reading the file. The 
other processes may, however, have accessed the file in an earlier state. 
Data already obtained by a program are not changed. The programmer must 
ensure that processes maintain a consistent view of a shared file. 

When you open a file, you specify the kind of access allowed on the file. 
When the file Is opened, the Operating System allocates a file marker for the 
calling process and a run-time Identification number called the refnum The 
process must use the refnum In subsequent calls to refer to the file. Each 
operation using the refnum affects only the file marker associated with that 
refniflTi. 

Processes can share the same file marker. In global access mode, each 
process uses the same refnum for the file. When a process opens a file In 
global access mode, the refnum It gets back can be passed to any other 
process, and used by any process. Note that any number of processes can 
open a file with Global.Refrvirt but each time the OPEN call Is used a 
different refnum Is produced. Each of those refnums can be passed to other 
processes, and each process using a particular refum shares the same file 
marker with other processes with the same refum. Processes using different 
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refnums, however always have different file markers, whether or not those 
refnums were obtained with Global.RefhLfTi 

A file can also be opened in private mode, which specifies that no other CPEN 
calls are to be allowed for that file. A file can be opened with 
Global_Reflnum and private, which qjens the file for gldjal access, ixit allows 
no other process to open that file. By using this call, processes can control 
which other processes have access to a file. The opening process passes the 
global refnum to any other process that is to have access, and the system 
prevents other processes from opening the file. 

Processes using global access may not be able to make any assumptions about 
the location of the file marker from one access to the next 

2.9 Pipes 

Because the operating System supports multiple processes, a mechanism is 
provided for interprocess communicatioa This mechanism is called a pipe 
Pipes are similar to the other objects in the File System ~ they are named 
according to \X^ same rules, and trwy can have labels. 

NOTE 

Pipes will not be supported in future releases of the Operating System. 
CX) not use the pipe mechanism if you want your software to be 
upward-compatible. 

As with a file, a pipe is a byte stream. With a pipe, however, information is 
queued in a first-in-first-out manner. Also, a pipe can have only one reader 
at a time, and once data is read from a pipe it is removed from the pipe. 

A pipe can be accessed only In sequential mode. Although only one process 
can read data from a pipe, any number of processes can write data into It. 
Because the data read from the pipe is consumed, the file marker is always at 
zero. If the pipe is empty and no processes have it open for writing, ECF (End 
Of File) is returned to the reading process. If any process has the pipe open 
for writing, the reading process is suspended until enough data to satisfy the 
call arrives in the pipe, or until all writers close the pipe. 

When a pipe is created, its size is bytes. Unlike with ordinary files, the 
initializing program must allocate space to the pipe before trying to write 
data into it To avoid deadlocks between the reading process and the writers, 
the Operating System does not allow a process to read or write an amount of 
data greater than half the physical size of the pipe. For this reason, you 
srwxild allocate to the pifw twice as much space as the lar^st amount of data 
in any planned read or write operatioa 

A pipe is actually a circular buffer with a read pointer and a write pointer. 
All writers access the pipe through the same write pointer. Whenever either 
pointer reaches the end of the pipe, it wraps back around to the first byte, if 
the read pointer catches up with the write pointer, the reading process blocks 
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until data are written or until all the writers close the pipe, similarly^ if the 
write pointer catches up with the read pointer^ a writing process blocks until 
the pipe reader frees up some space or until the reader closes the pipe. 
Because pipes have this structure^ there are restrictions on some operations. 
These restrictions are discussed with the relevant File System calls. 

Processes can never make read or write requests bigger than half the size of 
the pipe because the Operating System always fully satisfies each read or 
write request before returning to the program. In other words, if a process 
asks for 100 bytes of data from a pipe, the Operating System waits until there 
are 100 bytes of data in the pipe and then completes the call. Similarly, If a 
process tries to write 100 bytes of data Into a pipe, the Operating System 
waits until tliere is room for the full 100 bytes before writing anything Into 
the pipe. If processes were allowed to make write or read requests for 
greater than half of a particular pipe. It would be possible for a reader and a 
writer to deadlock, with neither having room in the pipe to satisfy Its 
requests. 

2.10 File System C^ls 

This section describes all the Operating System calls that pertain to the File 
System. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in the File System calls: 

Pathname = STRlMG[Max_Pathnaroe]; (» Max_Pathname = 255 *) 
E_NamB = STRING[l1ax_EnainB]; (* riax_ENaroe = 32 ») 
Accesses = (Dread, Dwrite, Append, Private, Glot)ai_Refnum); 
ttSet = SET OF Accesses; 
loHode = (Absolute, Relative, Sequential); 

The Fs_Info record and its associated types are described under the LOOKUP 
call. The Dctype record Is described under the DEVICE_C0NTR0L call. 
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2.iai MAKE_FILE and MAKE_P1PE File System Calls 

MAKE_FILE (Var Ecode:Integer; 
Var PatrtiPatnname; 
Label_Slze:Integer) 

MAKE_PIPE (Var Ecxrte: Integer; 
Var PathrPathname; 
Label_si2e : Integer) 

Ecode: Error indication 

Path: Mane of new object 

Label_Size: Number of bytes for the object's label 

MAKE_FILE and MAKE_PIPE create the specified type of object with the 
given name. If the pathname does not specify a directory name (more 
specifically, if the pathname does not begin with a dash), the working 
directory is used. Label_Size specifies the initial size in bytes of the label. 
It must be less than or equal to 128 bytes. The label can grow to contain up 
to 128 bytes no matter what its initial size. Any error indication is returned 
in Ecoda 

NOTE 

Pipes will not be siqaported in future releases of the Operating System. 
Do not use the pipe mechanism if you want your software to be 
upward-compatible. 



The MAKE_FILE example on the next page checks to see whether the 
specified file exists before opening it 
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CONST FlleExlStS = 890; 
VAR FileRefNuRt ErrorCode : INTEGER; 
FlleNaRie:PatnNaine; 
Happy -.BOOLEAN; 
Response :CHAR; 
BEGIN 

Happy:=FALSE; 
WHILE NOT Happy DO 
BEGIN 

REPEAT (» get a file name *) 

WITECFile name: *); 
READLN(FileNaine); 
UNHL LENG"m(FileNailie)>Q; 

HAKE_FILE(ErrorCocle^FlleNainB^O); («no label for this file*) 
IF (ErrorCodeoO) THEN (* does file already exist? *) 

IF (ErrorCode«FileExists) THEN (* yes *) 

BEGIN 

•RITE(FileNaniB, ' already exists. Overwrite? '); 
REAOLN(Response); 

Happy: ^(Response IN ['y', 'Y']); (*go ahead and overwrite*) 
END 

ELSE «RITELN( 'Error ', ErrorCode, ' i»hile creating file.') 
ELSE Happy :=TRUE; 
END; 

OPENCErrorCode^FileName^FlleRefNuRu [Dwrite]); 

END; 
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ZIOZ KILLJBJECT File system call 

KILLJBJECT (Var EcodB: Integer; 
Var PathzPatnnane) 

Ecode: Error Indicator 

Path: Name of object to be deleted 

KILL_GBJECT deletes the object given in Path from the File System. Objects 
with the safety switch on cannot be deleted. If a file or pipe is open at the 
time of the KILLJDBJECT call^ its actual deletion is postponed until it has 
been closed by all processes that have it opea During this period no new 
processes are allowed to open it. The object to be deleted need not be open 
at the time of the KILLJDBJECT call. A KILLJDBJECT call can be reversed 
by UNKILL_FILE^ as long as the object is a file and is still open. 

The following program fragment deletes files until RETURN is pressed: 

CONST FileN0tF0Und=894; 
VAR FileNanie:PathName; 
Errorcode : integer; 

BEGIN 
REPEAT 

•RITE( 'File to delete: '); 
REAOLN(FileNaiRe); 
IF (FileNaraeo") TMEN 
BEGIN 

KILLJBJECTCErrorCode^ FlleNarae); 
IF (ErrorOodeoO) THEN 
IF (ErrorCode=FlleNotFound) THEN 
•RnELNCFileMame/ not found.") 

ELSE iRITELNC Error '^Errorcode,' nhile deleting file.') 
ELSE iiRnELN<FileNarae/ deleted.'); 
END 
UNHL (FileNaiiie="); 
END; 



2-10 



operating System Reference Manual The File System 



2.ia3 UNKILL_FILE File System Call 

UNKILL_FILE (Var Ecode: Integer; 
RefNuRi: Integer; 
var Ne«naRie:e_naRie) 

Ecode: Error indicator 

RefNum: Refnum of the killed and open file 

Newname: New name for the file being restored 

UNKILL_FILE reverses the effect of KILL_CIBJECT as long as the killed 
object is a file that is still open. A new catalog entry is created for the file 
with the name given in Newname. Newname is not a full pathname: the 
resurrected file remains in the same directory. 
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2.m4 RErsiAME_EN7RY File system call 

RENAME_ENTRY (Var Ecocte: Integer; 
Var Path:Patnname; 
Var Nenname-.EJtame) 

Ecode: Error indicator 
Path: Object's old name 
Newname: Object's new name 

RENAMEJENTRY Changes the name of an object in the File System. 
Newname cannot be a full pathname. The name of the object is changed^ but 
the object remains in the same directory. The following program fragment 
changes the file name of FORMATTER.LIST to NEWFORMAT.TEXT. 

VAR OldNamerPathNaine; 
Ne«Naine:E_Name; 
ErrorCoderlNTEGER 

BEGIN 

oidNane: = * -Lisa-formatter .list*; 

NenNane : =: ' hE VFORhAT . TE XT ' ; 

RENAr€_ENiRV(ErrorCode. oldName. NetiNaine); 

END; 

The file's full pathname after renaming is 

-LISA-NEWFORMAT.TEXT 

Volume names can be renamed by specifying only the volume name in Path. 
Here is a sample program fragment which changes a volume name. Note that 
the leading dash {-\ given in CSdName^ is not given in NewName. 

VAR oidNameiPathName; 

Ne«Naine:E_Nanie; 

ErrorOode: INTEGER 
BEGIN 

OldName : = ' -thomas '; 

NewName: = ' steams'; 

RENAt€_ENTRY(ErrorGode, OldName, NenName); 
END; 
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2.ia5 LOOKUP File System call 

LOOKUP (Var Ecode: Integer; 
Var Path:Pathnaiiie; 
Var Attrldutes:Fs_Info) 

Ecode: Error indicator 

Path: Object to lookup 

Attributes: Information returned about path 

LOOKUP returns Information about an object in the file system. For devices 
and mounted volumes, call LOOKUP with a pathname that names the device or 
volume without a file name component: 

DevNainB:='-UPPER*; (* Diskette drive 1 ♦) 

LOOKUP(ErrorCode^ DevName^ Inf oRec); 

If the device is currently mounted and is block structured, all of the record 
fields of Attributes contain meaningful values; otherwise, some values are 
undefined. 

The Fs_lnfO record Is defined as follows. The meanings of the Information 
fields are given in Appendix E. 

FS_Inf0 = RECORD 

name: e^naRie; 
devnum: INTEGER; 
CASE OType:lnfo_type OF 

device_t, voli«nB_t: 

(iochannel: INTEGER 

devt: devtype; 

slot no: INTEGER; 

fs_sTze: LONGINr; 

VOl_slze: LONBINT; 

blod(structured^ 

mounted: BOOLEAN; 

opencount: LONGINT; 

prlvatedev^ 

remote, 

lockeddev: BOOLEAN; 

mount jjendlno, 

unmomt_pendlng: BOOLEAN; 

volname, 

password: e_name; 

fsversloru 

volld, 

volnum: INTEGER; 
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blockslze^ 

datasize, 

clustersize^ 

filecount: INTEGER; (*Nuraber of files on vol*) 



freecount: LONGINT; (^Nuntoer of free blocks 
DTVQ, (* Date Volume Created 
DTVB, (* Date Volume last Backed up 
DTVS:LGNGINT;(* Date Volume last scavenged 
riachlne_ia 
oveTroount_starap, 
master_copy_ld: LONGINT; 
privileged^ 

wrltejirotected: BOOLEAN; 
master^ 
copy, 

scavenge_flag: BOOLEAN); 
obJect_t: ( 

size: LONGINT; (-actual no of bytes written 
psize: LONGINT; ("physical size in bytes 
Ipsize: INTEGER; ("Logical page size in bytes 
ftype: filetype; 
etype: entrytype; 
DTC. 
DTA, 
DTTt 

DTB: LONGINT; 
refnura: INTEGER; 

fmark: LONGINT; (* file marker ») 
acinode: roset; (* access mode *) 
nreaders, (* Number of readers *) 
(* Number of writers *) 



•) 
*) 
*) 



(« Date Created 
(* Date last Accessed 
(* Date last Modified 
(« Date last Backed up 



INTEGER; 

uid; 



nwriters. 

nusers: 

fuid: 

eof, 

safetyjoa 

kswitch: BOOLEAN; 

private, ( 

locked, ( 



(* Number of users ») 
(* unique identifier *) 
(* EOF encountered? ») 
(* safety switch setting 
(* has file been killed? 

File opened for private access? 

Is file locked? *) 



END; 



protected :BOOLEAN);(* File copy protected? *) 
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Uld = INTEGER; 

Info_Type = (devlce_t^ volume_t, object_t); 

Devtype = (diskdev^ pascalDtt seqdev, DltOkt^ non.lo); 

Filetype = (undefined^ MDOFFile, rootcat, freelist^ 

badblocks. sysdata, spooL exec^ usercat. pipe. 

t)ootf lie. smpdata, swapcxxle. remap, userflle. 

kllledobject); 
Entrytype - (enptyentry. catentry. llnkentry. flleentry. 

plpeentry.ecentry. kllledentry); 

The eof field of the F$_lnfO record Is set after an attempt to read more 
bytes than are available from the file marker to the logical end of the file, or 
after an attempt to write when no disk space is available. If the file marker 
is at the twentieth byte of a twenty-five byte file^ for example, you can 
read up to 5 bytes without setting eof. but if you try to read 6 bytes, the 
File System gives you only 5 bytes of data and eof is set 

The following program reports how many bytes of data a given file has: 

VAR lnfoRec:Fs_lnfo;(»lrTfon?etlon returned by LOOKUP and INF0«) 
FlieNane-.PathName; 
Er rorCode : INTEGER; 
BEGIN 
KRITECFlle: '); 
READLN(FlleNaine); 

LOOKUP(ErrorCode. FlleName. inf oRec); 
IF (Errorcodeoo) THEN 
VRITELNCCannDt lookup '.FlleName) 

ELSE 

KRITELNCFlleNaroe. ' has MnfoRec.slze. ' bytes of data.'); 
END; 
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2.10.6 INFO File system CaU 

INFO (Var Ecode: Integer; 
RefNLM-.Integer; 
Var RefInfo:Fs_lnfo) 

Ecode: Error indicator 

RefNun: Reference number of object In File System 

Refinfo: Information returned about RefNum's object 

IhFO serves a function similar to that of LOOKUP but is applicable only to 
objects in the File System that are open. The definition of the Fsjnfo 
record is given under LOOKUP and in Appendix A. 
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2.10.7 SET_FILE_INFO File system call 

SET_FILE_INFO ( Var Ecode : Integer; 
RefNuRi: Integer; 
Fsl:FsJ[nfo) 

Ecode: Error indicator 

RefNum: Reference nuntoer of odject in File System 

Fsi : New Information about tne object 

SET_FILE_INFO Changes the status information associated with a given object. 
This call works in exactly the opposite way that LOOKUP and INFO work, in 
that the status information is given by your program to SET_FILE_INFQ The 
Fsi argument is the same type of information record as that returned by 
LOCKUP and INFQ The object must be open at the time this call is made. 

The following fields of the information report may be changed: 

file scavenged 
filejDlosed by_os 
flle_Ieft_open 
user_type 
user_subtype 
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2.1(L8 (PEN FUe System Call 

OPEN (Var Ecode: Integer; 
Var PathiPathnaine; 
var RefNum: integer; 

nanlp:nset) 

Ecode: Error indicator 

Path: Name of object to be opened 

RefNum: Reference number for object 

rianlp: Set of access types 

The (PEN call opens an object so that it can be read or written to. When 
you call CPEN, you specify the set of accesses that will be allowed on that 
file or sequential device. The available access types are: 

• Dread — Allows you to read the file 

• Mrite ~ Allows you to write in the file (to replace existing 
data) 

• Append ~ Allows you to add on to the end of the file 

• Private — Prevents other processes from opening the file 

• Global_Refnum ~ Creates a refnum that can be passed to other 
processes 

Note that you can give any number of these modes simultaneously. If you 
specify Dwrite and /^ppend in the same CPEN call^ Dwrite access will be used. 
See Section 2.8 for more information on Global_Refhum and Private access 
modes. 

If the object opened already exists and the process calls WRITE_DATA 
without having specified /Nppend access, the object can be overwritten. The 
Operating System does not create a temporary file and wait for the 
CLOSE JDBJECT call before deciding what to do with the old file. 

An object can be opened by two separate processes (or more than once by a 
single process) simultaneously. If the processes write to the file without using 
a global refnum, they must coordinate their file accesses so as to avoid 
overwriting each other's data. 

Pipes cannot be opened for Dwrite access. You must use /^ipend if you want 
to write into the pipe. To set up a private pipe, the reader process opens the 
pipe first, specifying Dread mode; the writer process then opens the pipe with 
/\pperKt Private access mode. 
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2.10.9 CLOSE_CBJECT File System Call 

CLOSEJBXCT (Var Ecode:Integer; 
RefNuni:Integer) 

Ecode: Error Indicator 

RefNum: Reference nuntoer of object to de closed 

If RefNum is not gloDal^ CLOSE_OBJECT terminates any use of RefNum for I/O 
operations. A FLUSH operation is performed automatically and the file is 
saved in its current state. If RefNum is a global refnum and other processes 
have the file open^ RefNum remains valid for these processes and other 
processes can still access the file using RefNum 

The following program fragment opens a file^ reads 512 bytes from it, and 
then closes the file. 

TYPE Byte=-128..127; 

VAR FlieName-.PatriNanie; 

ErrorCode^ FileRefNuni:Integer; 
ActualBytes :Longlnt; 
0uffer:/«RAY[O..511] OF Byte; 
BEGIN 
OPEN(ErrorCode^FlleNanie,FlleRefNunt [DRead]); 
IF (ErrorCode>0) THEN 

MRITELN( 'Cannot open '^FileName) 
aSE 
BEGIN 
READ_DATA(ErrorCode, 
FileRefNuiR, 
0RD4(iaBuffer), 
512, 

ActualBytes, 
Sequential, 
0); 
IF (ActualBytes<5l2) THEN 

•RITECOnly read *, ActualBytes, ' bytes from ',FileNaine); 
a0SE_0BJEGT(ErrorCoi3e, FileRef Num); 
END; 
END; 
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^laio READ_DATA and WRITE.DATA File System cau$ 

REAO.OATA (Var Ecodezlnteger; 
RefNum: Integer; 
Oata.AcMr :LongInt; 
Oount:Longlnt; 
Var Actual :LongInt; 
Mode:lohode; 
OffsetrLongint); 

VRITEJDATA (Var Ecode: Integer; 
RefNum: Integer; 
Data.Addr :Longlnt; 
Count:LongInt; 
var Actual :LongInt; 
rlode:loncx]e; 
Offset :Longlnt); 

Ecode: Error indicator 

RefNum: Reference number of object for I/O 

Data_Addr: Address of data (source or destination) 

Count: Number of bytes of data to be transferred 

Actual: Actual number of bytes transferred 

node: I/O mode 

Offset: Offset (absolute or relative modes) 

READJDATA reads Information from tne device^ plpe^ or file specified by 
RefNum, and WRITE J3ATA writes Information to It Data_Addr Is tne 
address for the destination or source of Count bytes of data, me actual 
number of bytes transferred is returned in Actual. 

Mode can be absolute, relative, or sequential, in absolute mode. Offset 
specifies an absolute byte of the file, in relative mode. Offset specifies a 
byte relative to the file marker, in sequential mode. Offset is ignored 
(assumed to be zero); transfers occur relative to the file marker. Sequential 
mode (which Is a special case of relative mode) is the only access mode 
allowed for reading or writing data in pipes or sequential (non-disk) devices. 
Non-sequential modes are valid only on devices that support positioning. The 
first byte Is numbered 0. 

If a process attempts to write data past the Physical End of File on a disk 
file, the Operating System automatically allocates enough additional space to 
contain the data. This new space, may not be contiguous with the previous 
blocks. You can use the ALLOCATE call to ensure that any newly allocated 
blocks are located next to each other, although they may not be located near 
the rest of the file. 

READJDATA from a pipe that does not contain enough data to satisfy Count 
suspends the calling process until the data arrives In the pipe, if there are no 
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writers, ine end-of-fiie indication (enor 848) is returned In Ecode. Because 
pipes are circular. WRITE_DATA to a pipe wltn insufficient room suspends the 
calling process (the writer) until enough space Is available (until the reader 
has consumed enough data). If no process has the pipe open for reading and 
there is not enough space In the pipe, the end-of-flle indication (848) Is 
returned In Ecode. 

NOTE 

READ_DATA from the MAINCONSOLE or ALTCONSOLE devices must 
specify Count - l. 

The following program copies a file. Note that you must supply the correct 
location for Syscall in the second line of the program. 

PROGRAh CopyFlle; 

USES (*Syscall.ObJ*) SysCall; 

TYPE By te=-128..127; 

VAR oldFlle.NenFlle-.PathName; 

OldRef Num Ne«Reft«jn:INlEGEa; 

BytesReatt Byteslfritten :L0NGINT; 

ErrorCode : INTEGER; 

Response.'CHAR; 

Buffer:ARRAY [0..511] OF Byte; 
BEGIN 
«RITE('Flle to copy: '); 
READLN(OldFile); 

OPEN(ErrorCode, OldFile, OldRefNunu [DRead] ); 
IF (ErrorCode>0) THEN 
BEGIN 

URITELNCError •.ErrorCode. ' while opening '.OldFlle); 

EXIT(CopyFlle); 
END; 

WRlTECNeip file name: '); 
READLN(NeiiFlle); 
MAKE FILE(EiTorCode.Ne«Flle.O); 
OPENTErrorCode,NeiiFlle^Ne«RefNURU [OVrlte]); 

REPEAT 

READ_DATA( ErrorCode, 

oldRefNunt 

0RD4(aBuffer). 

312, BytesRead, Sequential^ 0); 
IF (ErrorCode=0) AND (BytesRead>0) THEN 

•RITE_DATA (ElTOrCodB. 
NewRefNunt 
0RD4(aBuffer). 

BytesRead. BytesVritten. Sequential. 0); 
UNHL (BytesRead=0) OR (Bytesiiritten=o) OR (ErrorCode>0); 
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IF (Errorcode>o) twen 

•RITCLNCFile copy encountered error '^ErrorCode); 
aosE_OBJECT(ErrorCode. NenRefNum); 
CLOSEJOBJECT(ErrorCode^ OldRefNum); 
END. 
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z.iail READ_LABEL and WRITE_LA0EL File System calls 

READ.LABEL (Var Ecode: Integer; 
Var Path:Pathnane; 

Data_Addr :Longlnt; 

Count rLonglnt; 
Var Actual :Longlnt) 

•RI7E_LABEL (Var Ecode: Integer; 
Var Patn:Patnnaine; 

Data_Addr -.Longlnt; 

Count rLonglnt; 
Var Actual :LongInt) 

Ecode: Error Indicator 

Path: Name of object containing the label 

Data_Addr: Source or destination of I/O 

Count: Number of bytes to transfer 

Actual: Actual number of bytes transferred 

These calls read or write the label of an object in the File System. 1/0 
always starts at the beginning of the label. Count is the number of bytes the 
process wants transferred to or from Data_Addr. and /\ctual is the actual 
number of bytes transferred. An error is returned if you attempt to read 
more than the maximum label size^ 128 bytes. 
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z.iai2 DEYiCE_casfTRGL File system call 

0EVICE_C0NTR0L (Var Ecode:lnteger; 
Var PathrPathnarae; 
Var CPaiin:Dctype) 

Ecode: Error indicator 

Path: Device to be controlled 

CParm: A record of Information for the device driver 

DEVICEjCGNTROL is used to send device-specific information to a device 
driver or to obtain device-specific information from a device driver. 

Regardless of whether you are setting device-control parameters or requesting 
information, you always use a record of type Dctype. The structure of Octype 
is: 

Dctype = RECORD 

dcVersion: INTEGER; 

decode: INTEGER!; 

dCData: ARRAY[0..9] OF LONGINT 

END; 

dcVerslon: currently 2 

decode: control code for device driver 

dcoata: specific control or data parameters 

2.iai2.l Setting Device-Control Information 

Before you use a device, you call DEVICEjCONTROL to set the device driver. 
Once you begin using the device, you call DEVICEjCONTROL as necessary. 

Table 2-1 shows which groups of device-control functions must be set before 
using each type of device. Table 2-2 shows which characteristics are 
contained in each group. For example, you must set Group A for RS-232 
input. As you see in Table 2-2, Group A indicates the type of parity used 
with the device. Each group requires a separate call to DEVlCE_CorNrTROL, 
and you can set only one characteristic from each group. If you set more 
than one from the same group for a particular device, the last one set will 
apply. 
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Table 2-1 

DEVICE_C0NTR0L Functions Required 

before Using a Device 

Device Type Device Name Required Groups 

Serial RS~232 for RS232A or RS232B A, a D, E, F, G 

Input 

Serial RS-232 for RS232A or RS232B A. 8. a G. H.I 

output or printer 

ProFlle SLOTxCHANy (where J 

X and y are nuntoers) 
or PARAPORT 

Parallel printer SLOTxCHANy (where I 

X and y are numbers) 
or PARAPORT 

Console screen and MAINCONSOLE or I 

keyboard ALTCONSOLE 

Diskette drive UPPER or LOWER J 



Here is a sample program that shows how a device-control parameter is set. 
This program sets the parity attribute for the RS232B port to "no parity." 
Note that the parity attribute requires only that you set cparradccode and 
cpaim.dcdata[0]. Other parameters require that you also set cparm.dcdata[l] 
and cparm.dcdata(2j They are set in a similar manner. 

VAR 

cparin: dctype; 
errnum: integers- 
path: ji^thname; 

BEGIN 

path: = '-RS232B*; 

qMnii.dcversion:=2^- (* always set this value *) 



q3anR.ckX)ode:= 1; 
cpann.dcdata[Ol:= 0; 
DEVICE_CONTROL(ermunu path, cparm); 
I- 
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Table 2-2 shows how to set cpanadccode^ cpanacicciata[0], cparm.dcdata[l], 
and cpann.dcdata[2] for the various available attributes. Note that any values 
In cpaim.dcdata past cparm.dcdata[2] are Ignored when you are setting 
attributes documented here. 

Table 2-2 
DEVICE JXJNTROL Output Functional Groups 

FUNCTION .decode .dcdatafol .dcdataTll .dodataf2T 

Group A— Parity: 

No parity l o — — 
Odd parity, no i i __ __ 

input parity 

checking 
Odd parity, 1 2 — — 

input parity 

errors = 00 
Even parity, no l 3 

input parity 

checking 
Even parity, 1 4 — — 

input parity 

errors = $80 

Group B— Output Handshake: 
None 11 

DTR haidshctf<e 2 
XON/XOFF handshake 3 
delay after Cr, LF 4 ms delay 



Group C— Baud rate: 



baud 



Group D— Input waiting during Read^Data: 
wait for Count bytes 6 "o 
return whatever rec'd 6 l 

Group E— Input handshake: 

no handshake 7 

9 -1 -1 32767 

DTR handshake 7 

XON/XOFF handshake 8 
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Table 2-2 (continued) 

FUNCTION .decode .dcdatafol .dcdatafll .dcdatafzl 

Group F— Input typeahead buffer: 



flush only 9 
flush and re-size 9 
flush^ re-size^ 9 
and set threshold 


-1 

bytes 
bytes 


-2 
-2 

low 


-2 
-2 

hi 


Group 6— Disconnect Detection: 








none 10 
BREAK detected 10 
means disconnect 







non-zero 


~ 



Group H~Timeout on output (handshake interval): 

no timeout 12 
timeout enabled 12 seconds 

Group I~Automatic linefeed insertion: 

disabled 17 
enabled 17 l 

Group J— Disk errors (set to 1 to enable, to to disable): 
enable sparing 21 sparing rewrite reread 

Group K— Break conmand (never required — available only on serial 

RS-232 devices): 



send break 13 


millisecond 
duration 





— 


send break 13 


millisecond 


1 


— 


While lowering DTR 


duration 







Using Group c, you can set baud to any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

"Low" and "HI" under Group F set the low and high threshold in the typeahead 
input buffer. When "Hi" or more bytes are in the input buffer, XOFF is sent 
or DTR is dropped. When "Low" or fewer bytes are in the typeahead buffer, 
XC3N is sent or DTR is reasserted. The size of the typeahead buffer (bytes) can 
be any value between and 102« bytes inclusive. 

In Group J, enabling disk sparing permits the device driver to relocate blocks 
of data from areas of the disk that are found to be bad. Enabling disk rewrite 
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permits the operating System to rewrite data that It had trouble reading^ but 
finally managed to read. This condition is referred to as a soft error. 
Enabling disk reread tells the Operating System to read data after they are 
written to make certain that they were written correctly. 

When sending a break command^ as shown in Group K. any device control from 
Group A removes the break condition even if the allotted time has not yet 
elapsed. Also, sending a break will disrupt transmission of any other character 
still being sent. If you want to make certain that enough time has elapsed for 
the last character to be transmitted^ call WRITEJDATA with a single null 
character (equal to 0) just prior to calling DEVICEjCXNTROL to send the break. 

Table 2-3 gives a list of mnemonic constants that you can use in place of 
explicit numbers when setting Dccoda These mnemonics are provided for 
convenience. 

Table 2-5 
Decode Mnemonics 



Decode 


Mnemonic 


1 


dvParity 


2 


dvOutDTR 


3 


dvaitXON 


4 


dvOutDelay 


5 


dvBaud 


6 


dvlnwait 


7 


dvlnDTR 


8 


dvInXON 


9 


dvTypeahd 


10 


dvDlscon 


11 


dVOUtNOHS 


12 


no mnemonic 


13 


no mnemonic 


15 


dvErrStat 


16 


dvGetEvent 


17 


dvAutoLF 


20 


dvOiskStat 


21 


dvDiskSpare 



2.iai2.2 Gbtalr^ Device-Control information 

To use DEYICEjDONTROL to find out about the current state of a particular 
device^ simply Jve the pathname for the particular device along with a 
function code for the type of information you need. The record of type Octype 
that you supply is returned filled with information. 
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There are three types of Information requests you can make. Note that each 
type applies only to some of the available devices. The request types and the 
returned Information are described in Table 2-4. 

Table 2-5 shows the error code provided in response to a Dccode-15 
information request This code is given in cpaniuJodata[CQ. The code^ a long 
integer^ is shown in Table 2-5; the bits and bytes are numbered from the right 
counting from 0^ as shown in Figure 2-1. The meaning assigned to the bit 
applies if the bit is set (equals l). 



1 1 


b 


'in 


B 
■iii 


3 


: 


11 


b 


t 

iiii 


\ 
1 


2 


.; 


'■ '■ 


byte^ 


1 




byte 


J 

: 



•' 



7. 



7. 



7. 



Figure 2-1 
Disk Haand Enor oodes 

Here is a program fragment that uses DEVICEjCONTROL to get information 
about the upper diskette drive. 

VAR 

cperM: dctype; 

ermum: INTEGER; 

path: pathnane; 
BEGIN 

path: =• -UPPER*; 

cpani.doverslon:-^- (* always set this value *) 

cparn.dccode i- 20; 

DEVlCE_CGNTRf]L(errrejit path^ cparn); 

WITH cpaniDO 

VRIIELN (dcdata[0Ldcdata[l],dcdatar2Ldcdata[3L 
dcdata[4£dcdata[5L(lcdata[6]) 
END; 
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Table 2-4 
Device inf ormatlon 



Decode Devices 



Returned in Dcdata 



15 



Profiles 



16 



Console Screen 
and Keyboard 



[0] contains disk error status on 

last hardware error (see Table 

2-5) 

[1] contains error retry count 

since last system boot 

[0] contains numbers 0-10^ 
which indicate events: 

= no event 

1 = upper diskette inserted 

2 = upper diskette button 

3 = lower diskette inserted 

4 = lower diskette button 

6 = mouse button down 

7 = mouse plugged in 

8 = power button 

9 = mouse button up 
10 = mouse unplugged 

[1] contains the current state of 
certain keys^ indicated by set 
bits (if the bit is 1, the key is 
pressed) (bits are numbered from 
the right) 

= caps lock key 

1 = shift key 

2 = option key 

3 = commaid key 

4 = mouse button 

5 = auto repeat 

[2] contains X and Y coordinates 

of mouse, X in left 2 bytes, Y in 

right 2 bytes 

[3 J contains timer value in 

milliseconds 
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Decode Devices 



Table 2-4 (continued) 

Returned In Dcdata 



20 ProFlle or 

Diskette Drive 



[0] contains: 

= no disk present 

1 = disk present (but not 

accessed yet) 
The following indicate that a 
disk is present and has Deen 
accessed at least once. 

2 = bad block track appears 

unformatted 

3 = disk formatted by some 

program other than the 
Operating System 
A = OS-formatted disk 
[1] contains: 

= no button press pending 

1 = button press pending, 

disk not yet ejected 
[Z] contains number of available 

spare blocks^ 0-16, 

meaningful only when 

Dcdata[0] = 4 and for a 

diskette 
[3] contains; 

= both copies of the 

bad-block directory OK 

1 = one copy is corrupt 

(meaningful only when 
Dcdata[0] = 4) 
[4] contains: 

= sparing disabled 
i = sparing enabled 
[5] contains: 

= rewrite disabled 

1 = rewrite enabled 
[6] contains: 

= reread disabled 

1 = reread enabled 
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Table 2-5 
Disk Hard Error Codes 

Byte 3 

7 « ProFile received <> 55 to its last response 

6 = Write or write/verify aborted because more than 532 bytes of 

data were sent or because ProFile could not read its spare 
table 

5 «: Host's data is no longer in RATI because ProFile updated its 

spare table 

4 = SEEK ERROR — unable in 3 tries to read 3 consecutive headers 

on a track 

3 = CRC error (only set during actual read or verify of 

write/verify^ not while trying to read headers after seeking) 

2 = TIMEOUT ERROR (could not find header in 9 revolutions)— not 

set while trying to read headers after seeking 

1 s Not used 

» Operation unsuccessful 

Byte 2 

7 « SEEK ERROR — unable in i try to read 3 consecutive headers 

on a track 

6 » Spared sector table overflow (more than 32 sectors spared) 

5 - Not used 

4 = Bad block table overflow (more than 100 bad blocks in table) 

3 - ProFile unable to read its status sector 

2 ' sparing occurred 

1 = seek to wrong track occurred 

= Not used 

Byte 1 

7 « ProFile has been reset 

6 - Invalid block number 

5 = Not used 

4 s Not used 

3 a Not used 

2 - Not used 

1 > Not used 
s Not used 

Byte 

This byte contains the nurmber of errors encountered when rereading a 
block after any read error. 
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Z10.13 ALLOCATE FUe system Cau 

ALLOCAIE (Var Ecode:Integer; 
RefNLM:Integer; 
Oontlguous :Booleea* 
Oount:Longlnt; 
Var Actual :Integer) 

Ecode: Error Indicator 

RefNum: Reference nuinber of object to be allocated space 

Contiguous: True = allocate contiguously 

Count: Nuinber of blocks to be allocated 

Actual: Nurnber of blocks actually allocated 

Use /MJ_0CATE to Increase the space allocated to an object If possible^ 
ALLOCATE adds the requested number of blocks to the space available to the 
object referenced by RefNum. The actual number of blocks allocated is 
returned In Actual If Contiguous is true^ the new space is allocated in a 
single^ unfragmented space on the disk. This space is not necessarily adjacent 
to any existing file blocks. 

ALLOCATE applies only to objects on block-structured devices. An attempt to 
allocate more space to a pipe is successful only if the pipe's read pointer is 
less than or equal to its write pointer. If the write pointer has wrapped 
around but the read pointer has not an allocation would cause the reader to 
read invalid and uninitialized data, so the File System returns error 1186 in 
this case. 
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2.10.14 COMPACT File System Call 

COMPACT (Var Ecocte:Integer; 
RefNum: Integer) 

Ecode: Error Indicator 

RefNum: Reference number of object to be conpacted 

COMPACT changes the Physical End of File to deallocate any blocks after the 
block that contains the Logical End of File for the file referenced by RefNum. 
(See Figure 2-1.) COMPACT applies only to objects on block-structured 
devices. As in the case of ALLOCATE^ compaction of a pipe is legal only if 
the read pointer is less than or equal to the write pointer. If the write pointer 
has wrapped around, but the read pointer has not, compaction could destroy 
data in the pipe. The File System returns error 1188 In this case. 
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2.iai5 TRUNCATE File system call 

TRUNCATE (Var Ecode .-Integer; 
RefNun: Integer) 

Ecode: Error indicator 

RefNum: Reference nuniber of object to be truncated 

TRUNCATE sets the Logical End of File indicator to the current position of 
the file marker. Any data beyond the file marker are lost TRUNCATE 
applies only to block-structured devices. Truncation of a pipe can destroy 
data that have been written but not yet read. As the diagram shows, 
TRUNCATE Changes only LECF. COMPACT, on the other hand, changes only 

PECF. 
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old 
LEOF 



old 
PEOF 



Figure 2-2 
The RelaUonship of COMPACT and TRUNCATE 

In this figure the boxes represent blocks of data Note that LEOF can point to 
any byte in the file but PEOF always points to a block boundary. Therefore, 
TRUNCATE can reset LEOF to any byte in the file, but COMPACT can reset 
PEOF only to a block boundary. 
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Ziai6 FLUSH File system Cdll 

FLUSH (Var Ecode:lnteger; 
RefNiM:Integer) 

Ecode: Error Indicator 

RefNum: Reference number of destination of I/O 

FLUSH forces all buffered information destined for the object identified by 
RefNum to be written out to that object. 

A side effect of FLUSH Is that all FS buffers and data structures are flushed 
(as well as the control information for the referenced fileX If RefNum is -1^ 
only the global File System is flushed. This is a method Xii which an 
application can ensure that the File System is consistent 
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zmi7 SET.SAFETY FUe system cai 

SETJSAFETV (Var Ecx)d B|Intege r; 
Var PathzPathnaMB; 
onjoff -.Boolean) 

Ecode: Error Indicator 

Path: Name of odject cx)ntainlng safety switch 

OnjOff : Set safety switch: 

On « true 

Off a false 



Each object In the File System has a "safety switch" to help prevent accidental 
deletio a If the safety switch is on, the object cannot be deleted 
SETJSAFETY tums the switch on or off for the object identified by path. 
Processes that are sharing an object should cooperate with each other when 
setting or clearing the safety switch. 
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2.10.18 SET_WC)RKINGJDIR and GET_WORKINQ_DIR File System Calls 

SET_iORKING_DIR (Var Ecode: Integer; 
Var Path:PattYiame) 

GET_iORKING_DIR (Var Ecode: Integer; 
Var Patn:Patnname) 

Ecode: Error Indicator 
Path: Working directory name 

The Operating system uses the working directory name to resolve partially 
specified pathnames into complete pathnames. GET_WCRKING_DIR returns the 
current working directory name in Path. SET_WORKING_DIR sets the working 
directory name. 

The following program fragment reports the current name of the working 
directory and allows you to set it to something else: 

VAR iorkingDlr:PathName; 

ErrorCoderlNTEGER; 
BEGIN 

GET_WRiaNG_DIR(ErrorCode. Itorkingpir); 

IF (ErrorCodeoO) THEN 
KRITELNC 'Cannot get the current iporking directory!') 

ELSE IIRITELNCThe current working directory is: '^ iorkingDlr); 

lfRITE('Ne« working directory name: '); 

REAOLN(ltorklngDlr); 

SET_iORiaNG_OIR(ErrorOode^ ItorklngDlr); 
END; 
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2.iai9 RESET_CAT/>LOG and GET_NEXT_ENTRY File System Calls 

RESETJDATALOG (Var ECJOde: INTEGER; 
var Path:Pathname) 

GET_NEXT_ENTRY (Var ECOCte: INTEGER; 
Var Prefix, 

Entry :E_NaRe) 

Ecode: Error Indicator 

Path: Working directory name 

Prefix: Beginning of file names returned 

Entry: Names from catalog 

RESET_CAT/^LOG and GET_NEXT_ENTRY give a process access to catalogs. 
RESETJDATALOG sets the catalog file marker to the beginning of the catalog 
specified by Path. Path should he a root volume name. GET_NEXT_ENTRY 
then performs sequential reads through the catalog file specified in the 
RESETjCATALCG call and returns File System odject names. An end-of-file 
error code (848) is returned when GET_^EXT_E^4TRY reaches the end of the 
catalog. If Prefix Is non-null, only those entries in the catalog that begin with 
that prefix are returned. If Prefix is "AB", for example, only file names that 
begin with "AB" are returned. The prefix and catalog marker are local to the 
calling process, so several processes can simultaneously read a catalog without 
affecting each other. 
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ziozo MOUNT and UNMOUNT File System caus 

nouNT (var Ecoderinteger; 
Var VNaRe:EJIaRie; 
Var Passwird:Ejlaie 
Var DevnaMe:E_NaRie) 

iMloumr (var ECode:integer; 
Var vnamarEjiaiB) 

Ecode: Error indicator 

vname: Volume name 

Passwrd: Passiford for device (currently Ignored) 

Devname: Device name 

MOUNT and UNMOUNT handle access to sequential devices or block-structured 
devices. For block-structured devices^ MOUNT logically attaches the volume's 
catalog to the File System. The name of the volume mounted is returned in 
the \mame parameter. 

UNMOUNT detaches the specified volume from the File System. No object on 
that volume can be opened after unmount has been called. The volume 
cannot be unmounted until all the objects on the volume have been closed by 
all processes using them. 

Devname is the name of the device on which a volume is being mounted. 
Devname should be given without a leading dash (-). 

Vhame is the name of the volume that was successfully mounted^ and is 
returned. 
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A process is an entity in the Lisa system that performs work. When you ask 
the Operating System to run a program^ the OS creates a specific instance of 
the program and its associated data. That instance is a process. 

The Lisa can have a nurrtoer of processes at any one time; they appear to be 
running simultaneously. Although processes can share code and data, each 
process has its own stack. 

Only one process at a time can use the CPU. The Scheduler determines 
which process is active at a particular time. The Scheduler allows each 
process to run until some condition that would slow execution occurs (an I/O 
request^ for example). At that time, the running process is saved in its 
current state. The Scheduler then checks the pool of ready-to-run processes. 
When the original process later resumes execution, it picks up where it left 
off. 

The process scheduling state has three possiDllltles. A running process Is 
actually executing Instructions. A ready process is ready to execute but is 
being held back by the Scheduler. A OJocked p/ocess Is Ignored by the 
Scheduler. It cannot continue its execution until something causes it to 
become ready. Processes commonly become blocked while awaiting 
conrpletion of I/O, although there are a number of other likely causes. 
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3.1 Process Stnicture 

A process can use up to 16 data segments and 106 code segments. 

The layout of the process address space for user processes is shown in Figure 
3-1. 

Seg# 

♦-—■-— 





I Unavailable 



106 
+ — 

107 



122 

+— 

123 

+— 

124 



125 

^-. 

126 
♦— 

127 



User Code Segments 



LDSN 1 

(data segments) 

LDSN 16 

stack 

Shared Intrinsic Unit Data 

Screen 

Reserved 

Reserved 



Figure 3-1 
Process Address Space Laiyout 

Each process has an associated priority^ an integer between 1 and 255. The 
Scheduler usually executes the highest-priority ready process. The higher 
priorities (226 to 255) are reserved for the Operating System. 

32 Pnx»ss Hierarchy 

When the system is fint started/ several system processes exist At the base 
of the process hierarchy^ shown in Figure 3-2, is the root process, which 
handles various Internal Operating System functions. It has at least two sons: 
the Memory Manager process and the shell process. 

The Memory Manager process handles code and data segment swapping. 
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The shell process is a user process that is automatically started when the os 
is initialized. It is typically a command interpreter^ but it can be any 
program. The 08 simply looks for the program called SYSTEM.SHELL and 
executes it 



Root Process 




Memory Manager 

Process 

User 

Process 



Other User Processes 



Other 



Figure 3-2 
Process Tree 

Any other system process (the network control process, for example) is a son 
of the root process, 

3.3 Process Creation 

When a process is created^ it is placed in the ready state with a priority equal 
to that of the process that created it All the processes created by a given 
process can be thought of as existing in a subtree. Many of the process 
management calls affect the entire subtree of a process as well as the process 
Itself. 

3.4 Process Control 

Three system calls are provided for explicit control of a process. These calls 
allow a process to kill, suspend (block), or activate any other user process in 
the system, as long as the process identifier Is known. Process-handling calls 
are not allowed to control Operating System processes. 

3.5 Process Scheduling 

Process scheduling is based on the priority established for the process and on 
requests for Operating System services. 

The Scheduler generally executes the highest-priority ready process. Once a 
process is executing, it loses the CPU only under certain circumstances. The 
CPU is lost when there is some specific request for the process to wait (for 
an event, for example), when there is an I/O request, or when there is a 
reference to a code segment that is not in mennory. A process that makes 
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any operating System call may lose the CPU. The process gets the CPU back 
when the Operating System is finished^ except under the following conditions: 

• The running process requests input or output. The Scheduler starts the 
next highest-priority process running while the first process waits for the 
I/O to complete. 

• The running process lowers Its priority below that of another ready process 
or sets another process's priority higher than its own. 

• The running process explicitly yields the CPU to another process. 

• The running process activates a higher-priority process. 

• The running process suspends itself. 

• A higher-priority process becomes ready. 

• The running process needs code to be swapped into memory. 

• The running process executes an event-wait call. 

• The running process calls DELAY_TIME. 

Because the Operating System cannot seize the CPU from an executing 
process except In the cases noted above, background processes should be 
liberally sprinkled with YIELD_CPU calls. 

When the Scheduler is invoked^ it saves the state of the current process and 
selects the next process to run by examining the pool of ready processes. If 
the new process requires that code or data be loaded into memory, the 
Memory Manager process is launched. If the Memory Manager is already 
working on a process^ the Scheduler selects the highest priority process in the 
ready queue that does not need anything swapped. 

3.6 Process Termination 

A process terminates under one of the following conditions: 

• It calls TERMINATE_PROCESS. 

• It reaches an 'END.' statement. 

• It is referred to in a KILL_PROCESS call. 

• Its father process terminates. 

• It runs into an abnormal condition. 

When a process begins to terminate, a SYS_TERMINATE exception condition is 
signaled to the terminating process and all of the processes it has created. 
By means of the DECLARE_EXCEP_HDL call (described in Chapter 5), any 
process can create an exception handler to catch the terminate exception and 
clean up before terminating. The SYS_TERM1NATE exception handler will be 
executed only once. If an error occurs while the handler is executing, the 
process terminates immediately. 
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A process can call KILL_PROCESS on any user process whose Procjd Is 
known. TERMINATE_PROCESS, on the other hand^ terminates the process that 
called It (and Its descendants). TERMINATE_PROCESS also allows an event to 
be sent to the father of the terminating process If a local event channel was 
specified In the MAKE_PRCICESS call. 

Termination involves the following steps: 

1. Signal the SYS_TERM1NATE exception on the terminating process. 

2. Execute the user's exception handler, if any. 

3. Instruct all sons of the current process to terminate. 

a. Close all open files, data segmentspipes, and event channels left open by 
the user process. 

5. Send the SYS_SON_TERM event to the father of the terminating process 
if a local event channel exists. 

6. Wait for all the sons to finish termination. 

3.7 A Process-Handling Example 

The following programs illustrate the use of many of the process-management 
calls described in this chapter. The program Father, below, creates a son 
process and lets it run for a while. It then gives the user a chance to 
activate, suspend, kill, or get information about the son. 

PROGRAM Father; 

USES (*$U Source .-SysCall. Ob j*) SysCall; 

VAR ErrorCode : INTEGER; (*error returns from system calls *) 
proc_id:LONGINT; (* process global Identifier *) 
progname: Pathname; (* program file to execute *) 
nulliNameString; (* program entry point *) 

Info_Rec:ProclnfoRec; (* information about process *) 
i: INTEGER; 
Ansi»er:CHAR; 
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BEGIN 

ProgNane:»'SGN.OBJ'; (« this program is defined delor») 

Null:="; 

HAKE_PROCESS(ErrorCode. Proc_Id, ProgMame, Null, 0); 

IF (Erroroodeoo) THEN 

VRITELNC Error '^ErrorCode, ' during process management.'); 
FOR i:=l 7D 15 DO (• idle for awhile *) 

BEGIN 

•RI7ELN( 'Father executes for a moment.'); 

YIELD_CPU(ErrorCode, FALSE); (* let son run «) 
END; 

URITECKCill S(uspend A(ctivate I(nfo'); 
REAOLN(Ansver); 
CASE Answer OF 

'K','k': KlLLjW)CESS(ErrorCode,Procjd); 

'S'.'s': SUSPEND_PROCESS(ErrorCode.Proc_I(tTRUE (* suspend 

family *)); 

'A', 'a': ACnVATE_PROCESS(ErrorCode,Proc_IctTRUE (* activate 

family *)); 

•1','i': BEGIN 

INFO_PROCESS(ErrorCode, Proc_Ict Inf o_Rec); 

•RITELN('Son"s name is '.Info.Rec.ProgpathName); 

END; 
END; 
IF (ErrorCodeoO) THEN 

IIRITELN( 'Error '^ErrorOode, ' during process management.'); 

END. 

The program Son is: 

PROGRATISon; 

USES (*$U Source:SysCall.Obj*) SysCall; 

VAR ErrorCoderlNTEGER; 

null:NameString; 
BEGIN 

VHILE TRUE DO 
BEGIN 

URITELNCSon executes for a moment.'); 
YlELD_CPU(ErrorCode, FALSE); («let father process run*) 

END; 
END. 
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3.8 Process system Calls 

This section describes the operating System calls that pertain to process 
control. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in process-control calls: 

Pathname » S1RIN6[233]; 

Namestrlng = STRING[20]; 

P_s_eventblock = ''s eventblock; 

Sjeventblock = T__eweht J»>ct; 

TjBvent_text = airay [0..sizejBtext] of longlnt; 

ProcInfoRec = record 

progpathname : pathname; 

global^ld : longint; 

f ather_id : longlnt; 

priority : 1..255; 

state : (pactive, psuspended, pwaiting); 

data_in : boolean 

end; 
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3.8.1 MAKE_PROCESS PTocess System Call 

t1AKE_PR0CESS (Var ErrNuHi: Integer; 
Var Proc_Id:LongInt; 
Var ProgFile-.Patrmame; 

Var EntryNamB.-NameStrlng; (* NameString = STRING[20] *) 
Evnt_Chn_Ref Mum: Integer ) 

ErrNum: Error indicator 

Proc_Id: Process identifier (globally unique) 

ProgFile: Process file name 

EntryName: Program entry point 

Ev/nt_Chn_RefNum: Conimunication channel between calling 
process and created process 

A son process is created when another process^ the father process^ calls 
MAKE_PROCESS. The son process executes the program identified by the 
pathname in ProgFila If ProgFile is a null character string^ the program name 
of the father process is used. A globally unique identifier for the son process 
is returned in Proc_Id. 

Evnt_cnn_RefNum is a local event channel supplied by the father process. 
Event channels are discussed in Chapter 5. The Operating System uses the 
event channel identified by Evnl_cnn_RefNum to send the father process 
events regarding the son process (for example^ SYS_SON_TERM). If 
Evnt_Chn_RefNum is zero, the father process is not informed when such 
events are produced. 

EntryName^ if non-nulL specifies the program entry point where execution is 
to begin. Because alternate entry points have not yet been defined for 
Pascal, this parameter is currently ignored. 

Any error encountered during process creation is reported in ErrNum. 
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3.8^ TERMINATE_PR0CESS Process system Call 

TEW1INATE_PR0CESS(Var ErrNum : Integer; 

Event_Ptr :P_s_eventDlk) 

ErrNum: Error indicator 

E\/ent_Ptr: Information sent to process's creator 

A process can be ended Xi'^ TERM1NA7E_PR0CESS. This call causes a 
SYS_TERMINATE exception to be signaled for the calling process and for all 
of the processes it has created. The process can declare its own 
SYS_TERMINATE exception handler to handle whatever cleanup it needs to do 
before it is actually terminated by the system. When the terminate exception 
handler is entered^ the exception information block contains a longlnt that 
describes the cause of the process termination: 

Excep_Data[0] - Process called "nERMIFslATE_PROCESS. 

1 Process executed the 'EMD.' statement. 

2 Process called KILL_PROCESS on itself. 

3 Some other process called KILL_PROCESS on the 
terminating process. 

4 Father process is terminating. 

5 Process made an invalid system call (that is, an 
unknown call). 

6 Process made a system call with an invalid ErrNum 
parameter address. 

7 Process aborted due to an error while trying to swap 
in a code or data segment 

8 Process exceeded its maximum specified stack size. 

9 Process aborted due to possible lockup of the system 
by a data space exceeding physical memory size. 

10 Process aborted due to a parity error. 

There are an additional twenty-six erron that can be signaled. The entire list 
is shown at the beginning of Appendix A. 

If the terminating process was created with a communication channel, a 
SYS_SON_TERM event is sent to the terminating process's father. The 
terminating process can specify the text of the SYS_SON_TERM with the 
Event_Ptr parameter. Note that the first (0*th) longint of the event text is 
reserved by the system. When the event is sent to the father, the OS places 
the termination cause of the son process In the first longlnL This Is the same 
termination cause that was supplied to the terminating process itself in the 
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SYS_TERMINATE exception information block. Any user-supplied data in the 
first longint of the event text is overwrittea 

If a process specifies an event to be sent in the 7ERMINATE_PR0CESS call 
but the process was created without a local event channel, no event is sent to 
the father. 

If the process was created with a local event channeL an event is sent to the 
father if the process calls TERMBslATE_PRCXDESS with a nil Event_Ptr or if 
the process terminates by a means other than calling TERMINATEJ'ROCESS. 
The event contains the termination cause in the first longint and zeroes in the 
remaining event text 

P_$_eventblk is a pointer to sjeventbiK. defined as: 

CONST sizejBtext = 9; (• event text size - 40 bytes «) 
TYPE t_event_text = ARRAY [0..slze_etext] OF Longint; 
sjBventblk = t_event_text; 

If a process calls TERMINATE_PROCESS twice, the Operating System forces it 
to terminate even if it has disabled the terminate exception. 
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5.8.3 INFO_PROCESS Process System Call 

INFO_PROCESS (Var ErrNura: Integer; 
Proc_ld:Longlnt; 
Var Proc_Info:ProcInfoRec); 

ErrNun: Error indicator 

Proc_Id: Global identifier of process 
Proc_Info: Information adout tne process identified by 
Proc_Id 

A process can call lhFO_PROCESS to get a variety of information about any 
process known to the Operating System. Use the function MY_ID to get the 
Procjd of the calling process. 

ProcInfoRec is defined as: 

TYPE ProcInfoRec = RECORD 



ProgPathname 
Global id 
Priority 


•Pathname; 

Longint; 

1..255; 


State 
Data In 
END; 


(PActlve^ PSuspended^ Plaiting); 
Boolean 



Datajn indicates whether the data space of the process is currently in 
memory. 

The procedure on the next page gets information about a process and displays 
some of it. 
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PROCEDURE Dlsplay_Info(Proc_ICl:LONGINT); 
VAR ErrorCode : INTEGER; 

Inf o_Rec :ProcInf oRec; 
BEGIN 

lNFO_PROCESS(ErrorCocle, Proc_ld, Inf o_Rec); 
IF (ErrorCocle=100) THEN 

•RITELNC Attempt to display info about nonexistent 
process.') 
ELSE 
BEGIN 

ilTH Inf0_R8C DO 
BEGIN 

iRITELNC program name: ^ProgPathNarae); 
•RITELNC global id: ',Global_id); 
IfRITELNC' priority: ', prior ity); 
WRITEC state: •); 
CASE State OF 

PActive : IIRITELN( ' active ' ); 
PSuspended: liRITELN(' suspended'); 
PHaiting : iRITELN( ' waiting ' ) 
END 
END 
END 
END; 
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3.8.4 KILL_PROCESS Process system call 

KILLJWJCESS (Var ErrNuro: Integer; 
Proc_Id:LongInt) 

ErrNum: Error indicator 

Proc_Id: Process to be killed 

KILL_PROCESS kills the process referred to by Proc_Id and all of the 
processes in its subtree. The actual termination of the process does not occur 
until the process is in one of the following states: 

• Executing in user mode. 

• Stopped due to a SUSPElvD_PROCESS call. 

• Stopped due to a DELAY_TIME call. 

• Stopped due to a WAIT_EVEh4T_CHN or SEND_EVENT_CHN call, or 
READJDATA or WRITEJDATA to a pipe. 
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3.8.5 susPEND_PROCESS Process system Call 

SUSPEND_PROCESS (Var ErrNum: Integer; 
Proc_Id:LongInt; 
Susp_Faniily :Boolean) 

ErrNum: Error indicators 

Proc_Id: Process to be suspended 

Susp_Family: If true, suspend the entire process subtree 

SUSPEhD_PROCESS allows a process to suspend (block) any process in the 
system. The actual suspension does not occur until the process referred to by 
Proc_Id is in one of the following states: 

• Executing in user mode 

• Stopped due to a DELAY_TIME call 

• Stopped due to a WAITJEVENTjDHN call 

Neither expiration of the delay time nor receipt of the awaited event causes 
a suspended process to resume execution. SUSPEND_PROCESS is the only 
direct way to block a process. Processes, however, can become blocked during 
I/O, by the timer (see DELAY_TIME), or for many other reasons. 

If Susp_Famlly is true, the Operating System suspends both the process 
referred to by Procjd and all of its descendents. If Susp_Family is false, 
only the process identified by Procjd is suspended. 
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3.8.6 ACTIVATE_PR0CESS Process System Call 

ACnVATE_PROCESS(Var ErrNum: Integer; 
Proc_Id:LcjngInt; 
Act_Family : Boolean) 

ErrNum: Error indicator 

Proc_Id: Process to be activated 

Act_Family: If true^ activate the entire process subtree 

To awaken a suspended process^ call ACTIVATE_PRCICESS. A process can 
activate any other process in the system. Note that ACTIVATE_PROCESS can 
awaken only a suspended process. If the process is blocked for some other 
reason, ACTIVATE_PROCESS cannot unblock it. If Act_Famlly is true, 
ACT1VATE_PR0CESS also activates all the descendents of the process referred 
to by Procjd. 
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3.8.7 SETPRiORiTY_PRtx:£SS Process System call 

SETPfRIORITY_PROCESS(Var ErrNuTO : Integer; 

Proc_Id:LongInt; 
Ne«_Prlority : Integer ) 

ErrNum: Error indicator 

Proc_Id: Global id of process 

New_Priority: Process's new priority number 

SETPRICRITY_PROCESS changes the scheduling priority of the process 
referred to by Procjd to New_Priority. The priority value must be between 1 
and 225. (Operating System processes execute with priorities between 226 
and 255.) The higher the priority, the more likely the process is to be allowed 
to execute. 
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3.8.8 YIELDjCPU Process System Call 

YIELD_CPU(Var ErrNum: Integer; 
To_Any:Bcx)lean) 

ErrNum: Error indication 

To_Any: Yield to any process^ or only nigner or equal 
priority 

Background processes snould use YIELD_CPU often to allow other processes to 
execute when they need to. Successive yields by processes of the same 
priority result in a "round robin" scheduling of the processes. If To_Any is 
true^ YIELD_CPU causes the calling process to yield the CPU to any other 
ready process. If To_Any is false, YIELD_CPU causes the calling process to 
give the CPU to any other ready-to-execute process with an equal or higher 
priority. If no process meets the To_Any criterion, the calling process simply 
continues execution. 
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3.8.9 MY_ID Process System Call 

ttY_IO:Longint 

MY_ID is a function that returns the unique global identifier (a longint) of the 
calling process. A process can use MYJD to perform process handling calls 
on itself. 

For example: 

SetPrlorlty_Process(ErrNunt My_Id, 100) 

sets the priority of the calling process to 100. 
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Every process has a set of code segments and data segments which are in 
physical memory when they are used. The logical address used by the process 
must be translated into the physical address used by the memory controller. 
This function is handled by the memory management unit (MMU). 

4.1 Data Segments 

Each process has a data segment that the Operating System automatically 
allocates to it for use as a stack. The stack segment's internal structures are 
managed by the hardware and the Operating System. 

A process can acquire additional data segments for uses such as heaps and 
interprocess communication. These additional data segments can be private 
(or local ) data segments or shared data segments. Private data segments 
can be accessed only by the creating process. When the process terminates^ 
any private data segments still in existence are destroyed. Shared data 
segments can be accessed by any process that opens those segments. 

The Operating System requires that data segments be in physical memory 
before the data are referenced. The Scheduler automatically loads all of the 
data segments that the program says it needs. It is the responsibility of the 
programmer to ensure that the program declares all its needs by associating 
itself with the needed data segments before they are needed. 

This process of association is called tjinding. A program can bind a data 
segment to itself in several ways. When a program creates a data segment by 
using the MAKE_DATASEG call^ the segment is automatically opened and 
bound to the program. If a program needs to open a segment that was 
created by another program, the OPENJDATASEG call is used. That call binds 
the segment to the calling process, as well as opening the segment for the 
process. Since there may be times when a process needs to use more data 
segments than can be bound at one time, the UNBIND_DATASEG call is 
provided to unbind the data segment without closing it. The program can then 
use BIND_DATASEG to bind another data segment to the program. 

The Operating System views all data segments except the stack as linear 
arrays of bytes. Therefore, allocation, access, and interpretation of structures 
within a data segment are the responsibility of the program. 

4.2 ine Logical Data Segment Number 

The address space of a process allows up to 16 data segments bound to a 
process at the same time, in addition to the stack. Each bound data segment 
is associated with a specific region of the address space by means of a 
Logical Data Segment Number (LDSN). See Figure 3-1 for an illustration of 
the address space of a process. While a data segment is bound to the process, 
it is said to be a member of the working set of the process. 
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The process associates a data segment with a specific ldsn in the 

MAKEJDATASEG or CPENJDATASEG call. 

The LDSN^ Which has a valid range of 1 to 16, is local to the calling process. 
The process uses the LDSN to keep track of where a given data segment can 
be found. More than one data segment can be associated with the same LDSN, 
but only one such segment can be bound to a given LDSN at any instant and 
thus be a member of the working set of the process. 

4.3 Shared Data Segments 

Cooperating processes can share data segments. Shared segments cannot be 
larger than 128 Kbytes In length. As with local data segments, the segment 
creator assigns the segment a File System pathname. All processes that share 
that data segment then use the same pathname. If the shared data segment 
contains address pointers to data within the segment, the cooperating 
processes must also use the same LDSN with the segment. This ensures that 
all logical data addresses referencing locations within the data segment are 
consistent for the processes sharing the segment. A shared data segment is 
permanent until explicitly killed by a process. 

4.4 Private Data Segments 

Data segments can also be private to a process. In this case, the maximum 
size of the segment can be greater than 128 Kbytes. The actual maximum 
size depends on the amount of physical memory in the machine and the 
number of adjacent LDSNs available to map the segment. The process gives 
the desired segment size and the base LDSN to map the segment. The 
Memory Manager then uses ascending adjacent LDSNs to map successive 128 
Kbyte chunks of the segment. The process must ensure that enough 
consecutive LDSNs are available to map the entire segment. 

Suppose a process has a data segment already bound to LDSN 2. If the 
program tries to bind a 256 Kbyte data segment to LDSN 1, the Operating 
System returns an error because the 256 Kbyte segment needs two consecutive 
free LDSNs. Instead, the program should bind the segment to LDSN 3 and the 
system automatically also uses LDSN 4. 

4.5 Code Segments 

Division of a program into multiple code segments (swapping units) is dictated 
by the programmer through commands to the Compiler and Linker. The MMU 
registers can map up to 106 code segments. 

4.6 Swapping 

When a process executes, the following segments must be in physical memory: 

• The current code segment 

• All the data segments In the process working set (the stack and all bound 
data segments) 

The Operating System ensures that this minimum set of segments Is In physical 
memory before the process is allowed to execute. If the program calls a 
procedure in a segment not in memory, a segment swap-in request is Initiated. 
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In the simplest case^ this request only requires the system to allocate a block 
of physical memory and to read in the segment from the disk. In a worse 
case^ the request may require that other segments be swapped out first to 
free up sufficient memory. A clock algorithm is used to determine which 
segments to swap out or replace. This process is invisible to the program. 

4.7 Memory Management System Calls 

This section describes all the Operating System calls that pertain to memory 
management, A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in memory management 
calls: 

Pathname = STRING[255]; 

Tdstype = (ds_snare€t ds_private); 

DsInfoRec = Record 

ineiB_slze : longint; 

disc_slze : longint; 

nunbjopen : Integer; 

LDSN: Integer; 

boundF '.boolean; 

presentF : boolean; 

creatorF:boolean; 

r waccess : boolean; 

segptr: longint; 

volnamezejname; 
end; 
E_nane = string [32]; 
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IU.1 MflJt<E_D/KTfiSEG Memory Management System call 

hAKEJJATASEG (Var ErrNuBiiInteger; 
Var Segname: Pathname; 

MemjSlze, Olsk_slze:LongInt; 
Var RefNuro: Integer; 
Var SegPtrrLonglnt; 

Ldsn: Integer 

DstyperTdstype) 

ErrNum: Error indicator 

Segname: PatNname of data segment 

Mem_Siz8: Bytes of memory to be allocated to data segment 

Disk_Size: Bytes on disk to be allocated for swapping segment 

RefNum: Identifier for data segment 

SegPtr Address of data segment 

Ldsn: Logical data segment number 

Dstype: Type of dataseg (shared or private) 

MAKE_DATASEG creates the data segment identified by tbe pathname, 
Segname, and opens it for Immediate read-write access. Segname is a File 
System pathname. 

The parameter Mem_size determines how many bytes of main memory are 
allocated to the segment. The actual allocation takes place in terms of 
512-byte pages. If the data segment Is private (Dstype is (ls_prtvate), 
Mem_Slze can be greater than 128 Kbytes, but you must ensure that enough 
consecutive LDSNs are free to map the entire segment. 

DlskjSlze determines the number of bytes of swapping space to be allocated 
to the segment on disk. If Disk_Size is less than Mem_Size, the segment 
cannot be swapped out of main memory. In this case the segment is memory 
resident until it is killed or until its size in memory becomes less than or 
equal to its Dlsk_Size (see SIZE_DATASEG). The application programmer 
should be aware of the serious performance implications of forcing a segment 
to be memory resident. Because the segment cannot be swapped out, a new 
process may not be able to get all of its working set into memory. To avoid 
thrashing, each application should ensure that all of its data segments are 
swappable before it relinquishes the attention of the processor. 

The calling process associates a Logical Data Segment Number (LDSN) with 
the data segment. If this LDSN is bound to another data segment at the time 
of the call, the call returns an error. 

RefNum is returned by the system to be used in any further references to the 
data segment. The Operating System also returns SegPtr, an address pointer to 
be used to reference the contents of the segment. SegPtr points to the base 
of the data segment. 

Any error conditions are returned in ErrNum. 
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When a data segment is created^ It Immediately becomes a member of tne 
working set of the calling process. You can use UlsBIND_DATASEG to free 
the LDSN. 
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4w72 KILLJDATASEG Memory Management System Call 

KILL^DATASEG (Var ErrNum: Integer; 
Var Segnanie:Pathnaine) 

ErrNum: Error indicator 

Segname: Name of data segment to be deleted 

When a process is finished with a shared data segment^ it can issue a 
KILL_DATASEG call for that segment. (KILL DATASEG cannot be used on a 
private data segment.) If any process, including the calling process, still has 
the data segment operv the actual deallocation of the segment is delayed until 
all processes have closed it (see CX-OSEJDATASEG). During the interim period, 
however, after a KILLJDATASEG call has been issued but before the segment 
is actually deallocated, no other process can open that segment. 

KILLJDATASEG does not affect the membership of the data segment in the 
working set of the process. The RefNum and SegPtr values are valid until a 
CX.OSE_DATASEG call is issued. 

One important note: normally, when a data segment is closed, the contents 
are written to disk as a file with the pathname associated with the data 
segment. If, however, the program calls KILLJDATASEG on the data segment 
before closing It, the contents of the data segment are not written to disk and 
are lost when the segment is closed. 
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4.7.3 GPENJDATASEG Memory Mar\agemenl System call 

0PEN_DATASE6 (Var ErrNuTO: Integer; 
Var Segnanie:Pathnanie; 
Var RefNuni: integer; 
Var SegPtr:LongInt; 
Ldsn: Integer) 

ErrNum: Error indicator 

Segname: Name of data segment to be opened 

RefNum: Identifier for data segment 

SegPtr Pointer to contents of data segment 

Ldsn; Logical data segment number 

A process can open an existing shared data segment with OPENJDATASEG. 
The calling process must supply the name of the data segment (Segname) and 
the Logical Data Segment Number to be associated with it The LDSN given 
must not have a data segment currently bound to it. The segment's name is 
determined by the process that creates the data segment; it cannot be null. 

The Operating System returns both RefNum, an identifier for the calling 
process to use in future references to the data segment, and SegPtr. an 
address pointer used to reference the contents of the segment 

When a data segment is opened, it immediately becomes a member of the 
working set of the calling process. The access mode of the newly opened 
segment is Readonly. You can use SETACCESSJDATASEG to change the 
access rights to Readwrlte. You can use UNBIhDJDATASEG to free the 
LDSN. 

You cannot use CPEN on a private data segment, since calling CLOSE on a 
private data segment deletes It. 
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iUA CLOSE_DATASEG Memory Management system Cau 

CLOSE_DATASEG (Var ErrNuBi -.Integer; 
RefNum: Integer) 

ErrNum: Error indicator 
RefNum: Data segrnent identifier 

CLOSE_DATASEG terminates any use of Refh4um for data segment operations. 
If the data segment is bound to a Logical Data Segment Number^ 
CLOSE_DATASEG frees that LDSN. The data segment Is removed from the 
working set of the calling process. Ref?Mum is made invalid. Any references 
to the data segment using the original SegPtr will have unpredictable results. 

If RefNum refers to a private data segment CLOSE_DATASEG also kills the 
data segment deallocating the memory and disk space used for the data 
segment If RefNum refers to a shared data segment the contents of the 
data segment are written to disk as if FLUSH_DATASEG had been called. (If 
KILL_DATASEG is called before CLOSE_DATASEG, the contents of the data 
segment are thrown away when the last process closes the data segment.) 

Tt)e following procedure sets up a heap for LisaGraf using the memory 
management calls: 

PROCEDURE InltOataSeQForLlsaBraf (var ErrorCode: Integer); 

CONST HeapSize=16384; (* 16 KBytes for graphics heap •) 
DlskSlze=1638A; 

VAR HeapBuf rLONGINT; (* pointer to heap for LisaGraf *) 
GrafHeaprPathNaine; (* data segment path name *) 

Heap_Refnuin: INTEGER; (* refnum for heap data seg *) 

BEGIN 

GrafHeap : = ' grafheap ' ; 

OPEN_DATASEG(ErrorCode, GrafHeap^ Heap_Ref num, HeapBuf, l); 

IF (Errorcodeoo) THEN 

BEGIN 

WRITELN( 'Unable to open', Graf heap. 'Error is \ ErrorCode) 

END 

asE 

InitHe^(POINTER(HeapBuf ), POINTER(HeapBuf ^HeapSize), 
aHeapError); 
END; 
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4.7.5 FLUSH_DATASEG Memory Management System Call 

FLUSH_OATASEG (Var ErrNum : Integer; 
RefNuni: Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

FLUSH_DATASEG writes tne contents of tne data segment identified by 
RefNum to tne disk. (Note tnat CLOSE_DATASEG automatically flusnes tne 
data segment before closing it, unless KILL_DATASEG was called first.) Tnis 
call has no effect upon the memory residence or binding of the data segment. 
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4.7.6 SIZE_DATASEG Memory Management system call 

SIZE_DATASEG (Var ErrNuni: Integer; 

Refnum: Integer; 

DeltanemSize : Longint; 
Var Ne«riefi6ize:LongInt; 

OeltaOlskSize : Longint; 
Var NewOisRSlze: Longint) 

ErrNum: Error indicator 

RefNum: Data segment identifier 

DeltaMemSize: Afnount in Dytes of change in memory 

allocation 

NewMemSize: New actual size of segment in memory 

DeltaOiskSize: Amount in bytes of change in disk allocation 

NewDiskSize: New actual disk (swapping) allocation 

SIZEJDATASEG Changes the memory and/or disk space allocations of the data 
segment referred to by RefNum. Both DeltaMemSize and DeltaOiskSize can 
be either positive^ negative^ or zero. The changes^ to the data segment take 
place at the high end of the segment and do not destroy the contents of the 
segment unless data are lost in shrinking the segment. Because the actual 
allocation is done in terms of pages (512-byte blocks), the NewMemSize and 
NewDiskSize returned by SIZE_DAT/\SEG may be larger than the old size plus 
delta size of the respective areas. 

If the NewDlskSlze is less than the NewMemSize, the segment cannot be 
swapped out of memory. The application programmer should be aware of the 
serious performance implications of forcing a segment to be memory resident. 
Because the segment cannot be swapped out a new process may not be able 
to get all of its working set into memory. To avoid thrashing, each 
application should ensure that all of its data segments are swappable before it 
relinquishes the attention of the processor. 

If the necessary adjacent LDSNs are available, SIZEJDATASEG can increase 
the size of a private data segment beyond 128 Kbytes. 
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iUJ INF0_DATASEG Menwiy Management System Call 

INFOJMTASEG (Var EnNURi: Integer; 
RefNum: Integer; 
Var DsInfo:DsInfoRec) 

ErrNum: Error indicator 

RefNum: Identifier of data segment 

Dslnfo: Attributes of data segment 

INFO_DATASEG retums information about a data segment to tne calling 
process, me staicture of the DslnfoRec record is: 

RECORD 

Heffl_Size:LongInt (* Bytes of memory allocated to data segment 
DiscjSize:Longlnt (* ^ftes of disk space allocated to segment 
NumbOpen:Integer (* current number of processes with segment open « 
Ldsn: Integer (* LOSN for segment binding 
BoundF:Boolean (* True If segment Is bound to LDSN of calling proc * 
PresentF:6oolean (* True If segment Is present in memory 
CreatorF:Booleanm (* True If the calling process is the creator 

(* of the segment 
RiAccess:Boolean (« True if the calling process has Vrlte access * 
(* to segment 

END; 
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4w7.8 INF0_LDSN Memory Management system Call 

Ilf'O.LDSN ( Var ErrNuni:Integer; 
Ldsn: Integer; 
Var RefNuR: Integer) 

ErrNum: Error Irwlicator 

Ldsn: Logical data segment numtier 

RefNum: Data segment identifier 

IhFOJ_DSN returns the refnum of the data segment currently tjound to Ldsa 
You can then use IhFO_DATASEG to get information about that data segment. 
If the LDSN specified is not currently bound to a data segment, the refnum 
returned is -1. 
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tU3 I^FO_/^DDRESS Merroiy Management System C^^ 

INFO_ADORESS (Var ErrNuTO: Integer; 
Address :Longint; 
Var RefNunt: Integer) 

ErrNum: Error indicator 

Address: The address about which the program needs information 

RefNum: Data segment identifier 

This call returns the refnum of the currently bound data segment that 
contains the address given. 

If no data segment that contains the address given Is currently bound to the 
calling process, an error indication is returned in ErrNum 
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4^7.10 MEMJNFO Memory Management system cai 

roi_iNFO (Var ErrNum: integer; 
Var Svapspace; 
Dataspace; 
Ciir_codesize; 
Haxjcodesize :Longlnt ) 

ErrNum: Error indicator 

Amount, in bytes, of swappable system memory 

available to the calling process 

Amount, in bytes, of system memory that the 

calling process needs for its bound data areas, 

including the process stacK and the shared 

intrinsic data segment 

Size, in bytes, of the calling segment 

Size, in bytes, of the largest code segment 

within the address space of the calling process 

This call retrieves information about the memory resources used by the calling 
process. 



Dataspace: 



Cur_codesize: 
Max codesize: 
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4w7.li SETACCESS_DATASEG Memory Management System Call 

SETACCESS_0ATASE6 (Var ErrNum : Integer; 

RefNum: Integer; 
Readonly :Boolean) 

ErrNum: Error indicator 
RefNum: Data segment identifier 
Readonly: Access mode 

A process can control the kinds of access it is allowed to exercise on a data 
segment with the SETACCESSJDATASEG call. Refnum is the identifier for 
the data segment. If Readonly is true^ an attempt by the process to write to 
the data segment results in an address error exception condition. To get 
readwrite access^ set Readonly to false. 
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4.7.12 BlhD_DATASEG and UNBIND_DATASEG Memory Management System Calls 

BIM)_OATASEG(Var ErrNuTO: Integer; 
RefNum: Integer) 

UNBIND_0ATftSE6(Var ErrNum: Integer; 
RefNuin:Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

B»>D_DATASEG binds the data segment referred to by RefNum to its 
associated Logical Data Segment Number(s). UNBINDJDATASEG unbinds the 
data segment from its LDSNs. BINDJDATASEG causes the data segment to 
become a member of the current working set. At the time of the 
BIND_DATASEG call, the necessary LDSNs must not be bound to a different , 
data segment. UNBINDJDATASEG frees the associated LDSNs. A reference to 
the contents of an unbound segment gives unpredictable results. 
CPENJDATASEG and MAKEJDATASEG define Which LDSNs are associated 
with a given data segment. 
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Processes have several ways to keep informed about the state of the system. 
Normal process-to-process communication and synchronization employ pipes, 
shared data segments, or events. Abnormal conditions, including those your 
program may define, employ exceptions (interrupts). Exceptions are signals to 
which the process can respond in a variety of ways under your control. 

5.1 Exceptions 

Normal execution of a process can be interrupted by an exceptional condition 
(such as division by zero or reference to an invalid address). Some error 
conditions are trapped by the hardware and some by the system software. The 
process itself can define and signal exceptions of your choice. 

When an exception occun, the system first checks the state of the exception. 
The three exception states are: 

• Enabled 

• Queued 

• Ignored 

If a system-defined exception Is enabled the system looks for an associated 
user-defined handler. If none is found, the system invokes the default 
exception handler, which usually aborts the process that generated the 
exception. If a user-defined exception is enabled, the system invokes the 
associated user-defined exception handler. You create a new exception by 
declaring and enabling a handler for it. 

If the state of the exception is queued the exception is placed on a queue. 
When the exception Is subsequently enabled, the queue Is examined and the 
appropriate exception handler Is Invoked. Processes can flush the exception 
queue. 

If the state of the exception is ignored the system detects the occurrence of 
the exception, but the exception is neither honored nor queued. Note that 
ignoring a system-defined exception has uncertain effects. Although you can 
cause the system to ignore even the SYS_TERMINATE exception, that 
capability is provided so that your program can clean up before terminating. 
You cannot set your program to ignore fatal errors. 

Invocation of the exception handler causes the Scheduler to run, so it is 
possible for another process to run between the signaling of the exception and 
the execution of the exception handler. 
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52 SystenrHDeflned Exceptions 

Certain exceptions are predefined by the Operating System. These include: 

• Division by zero (SYS_ZERO_DIV). The default handler aborts the process. 

• Value out of bounds (that Is^ range check error) or illegal string index 
(SYS_VALUE_OOB). The default handler aborts the process. 

• Arithmetic overflow (SYS_OVERFLOW). The default handler aborts the 
process. 

• Process termination (SYS_TERM1NATE). This exception is signaled when a 
process terminates^ or when there is a bus error^ address error^ illegal 
instruction^ privilege violation^ or 1111 emulator enor. The default handler 
does nothing. This exception Is different from the other system-defined 
exceptions in that the program always terminates as soon as the exception 
occurs. In the case of other (non-fatal) errors, the program is allowed to 
continue until the exception is enabled. 

Except where otherwise noted, these exceptions are fatal if they occur within 
Operating System code. The hardware exceptions for parity error, spurious 
interrupt, and power failure are also fatal. 

5.3 Exception Handlers 

A user-defined exception handler can be declared for a specific exception. 
This exception handler is coded as a procedure but must follow certain 
conventions. Each handler must have two input parameters: Environment_Ptr 
and Data_Ptr. The Operating System ensures that these pointers are valid 
when the handler is entered. Environment_Ptr points to an area in the stack 
containing the interrupted environment: register contents, condition flags, and 
program state. The handler can access this environment and can modify 
everything except the program counter, register A7, and the supervisor state 
bit in the status register. Data_Ptr points to an area in the stack containing 
Information about the specific exception. 

Each exception handler must be defined at the global level of the process, 
must return, and cannot have any EXIT or global GOTO statements. Because 
the Operating System disables the exception before calling the exception 
handler, the handler should re-enable the exception before it returns. 

If an exception handler for a given exception already exists when another 
handler is declared for that exception, the old handler becomes dissociated 
from the exception. 

An exception can occur during the execution of an exception handler. The 
state of the exception determines whether it is honored^Jlaced on a queue, or 
ignored. If the second exception has the same name as the exception that is 
currently being hcffidled and its state is enabled, a nested call to the exception 
handler occurs. (The system always disables the exception before calling the 
exception handler, however. Therefore, nested handler calling occurs only if 
you explicitly enable the exception.) 
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There is an exception-occurred flag^ Ex_occurred_f, for every declared 
exception; it is set whenever the corresponding exception occurs. This flag 
can be examined and reset using the ihFOjEXCEP system call, once the flag 
is set^ it remains set until FLUSH_EXCEP is called. 

The following program fragment gives an example of exception handling. 

PROCEDURE Handler (EnvIronment_Ptiip_envJ)lk; 

Data_PtKp_ex_data); 
VAR ErrNumdNTEGER; 
BEGIN 

(*Envlronment_Ptr points to a record containing the program *) 
(^counter and all registers. Data_Ptr points to an array of 12 *) 
(*longints that contain the event header and text if this handler *) 
(*is associated with an event-call channel (See below) *) 



ENABLE_EXCEP(ermumjBxcep_name); 

END; 

BEGIN (*Main program*) 



Excep_name:-'EndOfDoc'; 
DECLARE_EXCEP_HDL(ermumjexcep_namejiHandler); 



slGNAL_EXCEP(erfmum^xcep_name^xcep_dataX- 



At the time the exception handler is invoked for a SYS_TERMINATE 
exception^ the stack is as shown in Figure 5-1. 
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low address 



'^^^ 
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Program Counter 



Data Ptr 
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Terminate Flag 



Exception Kind 
Function Code (fc) 
Access Address (aa) 
Instaictim Register 

Status Register 
Program Counter 



Program Comter 

Status Register 

D0-D7 and A0-A7 



Link 



Program Ctxinter 



Exception Data Block 
(SYS_TERMINATE Exception) 



Exception Environment Block 



high address 



Figure 5-1 
Stack at Exception Handler Invocation 

The Exception Data Block given here reflects the state of the stack upon a 
SYS_TERMINATE exception. The Term_Ex_Data record (described in Appendix 
A) gives the various forms the data block can take. The Excep_Kind field (the 
first, or 0th, longint) gives the cause of the exception. The status register and 
program counter values in the data block reflect the true (current) state of 
these values. The same data in the Environment block reflects the state of 
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these values at the time the exception was signaled, not the values at the 
time the exception actually occurs. 

For SYS_ZER0_D1V, SYS_VALUE_OCB, and SYS_OVERFLOW exceptions, the 
Hard_Ex_Data record described in Appendix A gives the various forms that 
the data block can take. 

In the case of a bus or address error, the PC (program counter) can be 2 to 10 
bytes beyond the current instruction. The PC and A7 cannot be modified by 
the exception handler. 

When a disabled exception is re-enabled, a queued exception may be signaled. 
In this case, the exception environment reflects the state of the system at the 
time the exception was re-enabled, not the time at which the exception 
occurred. 

5.4 Events 

An event is a piece of information sent by one process to another, generally 
to help cooperating processes synchronize their activities. An event is sent 
through a kind of pipe called an event channel. The event is a fixed-size 
data block consisting of a header and some text. The header contains control 
information, the identifier of the sending process, and the type of the event. 
The header is written by the system, not the sender, and is readable by the 
receiving process. The event text is written by the sender; its meaning is 
defined by the sending and receiving processes. 

There are several predefined system event types. The predefined type "user" is 
assigned to all events not sent by the Operating System. 

5.5 Event Channels 

Event channels can be viewed as higher-level pipes. One important difference 
is that event channels require fixed-size data blocks, whereas pipes can 
handle an arbitrary byte stream. 

An event channel can be defined globally or locally. A global event channel 
has a globally defined pathname catalogued in the File System and can be 
used by any process. A local event channel, however, has no name and is 
known only by the Operating System and the process that opened it Local 
event channels can be opened by user processes only as receivers, A local 
channel can be opened by the father process to receive system-generated 
events pertaining to its son. 

There are two types of global and local event channels: event-wait and 
event-call. If the receiving process Is not ready to receive the event, an 
event-wait type of event channel queues an event sent to It . An event-call 
type of event channel, however, forces Its event on the process. In effect 
treating the event as an exception, in that case, an exception name must be 
given when the event-call event channel Is opened, and an exception handler 
for that exception must be declared. If the process reading the event-call 
channel is suspended at the time the event Is sent, the event Is delivered 
when the process becomes active. 
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When an event channel is created, the Operating System preallocates enough 
space to the channel for typical interprocess communication. If 
SErsD_EVENT_CHN is called when the channel does not have enough space for 
the event, the calling process is blocked until enough space is freed up. 

If WAIT_EVENT_CHN is called when the channel is empty, the calling process 
is blocked mtil an event arrives. 

The following code fragments use event-wait channels to handle process 
synchronization, operating System calls used in these program fragments are 
documented later in this chapter. 

Process A: 



chnjiame := *event_channel_r; 

exception: = "; 

receiver := TRUE; 

OPEN_EVENTjCHN (errint, chn_naine, ref nuna^ exception, receiver); 

chnjname := 'eventjDhannel_2V 

receiver := FALSE; 

OPEN_EVENT_CHN (errint, chn_name, refnum2, exception, receiver ); 

•paitlist. length := 1; 

ipaitlist.refnuRi[0] := refnuml; 

REPEAT 

eventl_ptr*.[0] := agreedjuponj/alue; 

interval. sec := 0; (* send event ifunediately *) 

interval. iRsec := 0; 

SEND_EVENT_CHN (errint, ref nuHi2„ eventl_ptr, interval, clktiine); 

•AIT_EVENT_CHN (errint, waitlist, refnum_signaling, event2_ptr); 



(* processing performed here *) 
UNHL AllOone; 
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Process B: 



chnjiame := •event_channel_2'; 

exception := "; 

receiver := TRUE; 

C)PEN_EVENT_CHN (errlnt^ cm_name^ refmimZ^ exceptloa receiver); 

ctYijiame := *event_crennel_r; 

receiver := FALSE; 

(]PEN_EVENT_CHN (errlnt^ ctmjiame^ ref nunil, exception, receiver); 

•aitllst. length := 1; 

i»itlist.refnuni[0] := refnumi; 

REPEAT 

event2j]tr^.[0] := agreedjjpon_valiie; 

Interval. sec := 0; (* send event imnediately *) 

interval. msec := 0; 

•AIT_EVENTJCHN (errlnt^ waitlist^ refnuRi_signallng, eventljrtr); 



(* processing performed here *) 



SEND_EVENT_CHN (errlnt^ ref numZ, event2_ptr, intervals clktime); 
UNHL AllOone; 



The order of execution of the two processes is the same regardless of the 
process priorities. Process switch always occurs at the WAIT_EVB^_CHN 
call. 

In the following example using event-call channels, process switch may occur 
at different places in the programs. Process A calls YIELDjCPU, which gives 
the CPU to Process B only if Process B is ready to rua 
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Process A: 



PROCEDURE Handler(Envj>tr:pjenM_blK; 
Oata_ptT :p_exjJata); 



BEGIN 

event2_ptr''.[0] := agreedjuponj/alue; 



{* processing perfoned rere «) 



Interval. sec :» 0; (* send event iMBdiately *) 
interval. msec :* 0; 

SEND_EVEWT_CHN (errlnt^iefrtJCeMentZjJtr^ Interval, clktime); 
tojany :» true; 
YIELD_CPU (errlnt, tojany); 
END; 

BEGIN <* Haln program*) 



DECLflRE_EXCEPJCL (errint, excep_naiBe_l. anandler ); 

cnnjiaiie := *event_channel_r; 

exception :== exDep_naiiiB_l; 

receiver := TRUE; 

OPEN_EVENT_CHN (errint. chn_nanie. ref numl. exception, receiver); 

Ghnjiame := *event_criannel_2'; 

receiver :» FALSE; 

exception: = "; 

OPEN_EVENT_CHN (errint.chnjwBB.refnuiii^exceptioa receiver); 

SEND_EVENT_CHN (errlnt, refntnC event2jptr, intervaL clktime); 

tojany :» true; 

YiaojDPU (errint, tojany); 
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Process & 



PROCEDURE Handler(Envj)tr:p_envj)lK; 
Dataj)tr :p_ex_data); 



BEGIN 

event2j)tr.[03 := agreed_upon_value; 

(* processing performed here *) 



interval. sec := O; (* send event iinroediately ») 
interval. msec := 0; 

SEND_EVENT_CHN (errlnt. ref numl. event2j)tr, IntervaL clktline); 
to any := true; 
YiaD_CPU (errint.to any); 

END; 



BEGIN (*rtaln program *) 

DECL/\RE_EXCEP_HDL (errint, excep_naHiBj l,aH»Kller) 

chn_namB := •event_channel_l'; 

exception := excep_namB_l; 

receiver "= F/tf_SE; 

exception := "; 

C]PEN_EVENT-CHN (errint, chn_naiiiB, refnurol, exception, receiver); 

chn_nainB := •event_cnannel_2*; 

receiver := TRUE; 

OPEN_EVENT_CHN (errint, cnn_nawe, ref nune, exception, receiver); 



END. 
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5.6 ine System Clock 

A process can read the system clock time, convert it to local time, or delay 
its own continuation until a given time. The year, month, day, hour, minute, 
second, and millisecond are available from the clock. The system clock is set 
up through the Workshop shell. For more Information, see the work^wp User's 
Guide for the Lisa, 

5.7 Exception Management System Calls 

This section describes all the operating System calls that pertain to exception 
management A summary of all the Operating System calls can be found In 
Appendix A. The following special types are used In exception management 
calls: 

TjBXjrame = S1BIN6[16]; 

Lon^dr » ^longlnt; 

T_exjdata = Array [0..113 of longlnt; 

T_ex_sts = Record 

ex_occurred_f :boolean; 

ex_sta[te : t_ex_state; 

nuiRjexcep: integer; 

hdljadr : longadr; 
end; 
T_ex_state = (enabled, queuett ignored); 
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5.7.1 DECLARE_EXCEP_HDL ExcepUon Management System Call 

DECLARE_EXCEP_HDL ( Var ErrNum: Integer; 

Var Excep_NaBie:t_ex_nainB; 
Entry_Point :LongAdr ) 

ErrNum: Error indicator 

Excep_Nafne: Name of exception 
Entry_Point: Address of exception handler 

C£CLARE_EXCEP_HDL sets the Operating System so that the occurrence of 
the exception referred to by Excep_Name causes the execution of the 
exception handler at Entiy_PoinL 

Excep_Name is a character string name with up to 16 characters that is 
locally defined in the process and known only to the process and the Operating 
System. If Entry_Polnt Is nil and ExDep_Name specifies a system exceptioa 
the system default exception handler is used. Any previously declared 
exception handler is dissociated by this call. The exception itself is 
automatically enabled. 

If any ExcepJMame exceptions are queued at the time of the 
DECLARE_EXCEP_HDL call^ the exception is automatically enabled and the 
queued exceptions are handled by the newly declared handler. 

You can call DECL/\RE_EXCEP_HDL with an exception handler address ofnil 
to dissociate your handler from the exception. If there is no system handler 
defined^ the program that signals the exception receives an error 201. 
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SJ2 DISABLE_EXCEP Exception Management System cau 

DISABLE_E)(CEP <Var ErrNumrlnteger; 

Var Excep_Name:t ex_namB; 
QueueiBooleany 

ErrNum: Error indicator 

ExcepjNJame: Name of exception to de disabled 

Queue: Exception queuing flag 

A process can explicitly disable tne trapping of an exception by calling 
DIS/^BLE_EXCEP. ExcepJMame is tne name of tne exception to be disabled. 
If Queue is true and an exception occun, tne exception is queued and is 
handled when it is enabled again. If Queue is false^ tne exception is ignored. 
When an exception handler is entered^ the state of the exception in question 
is automatically set to queued. 

If an exception handler is associated through CPENJEVENTjCHN with an 
event channel and DISABLE_EXCEP Is called for that exception^ thea- 

• If Queue is false, and if an event is sent to the event channel by 
SEND^EVENTjCHN, the SEND_EVENT_CHN call succeeds, but it is 
equivalent to not calling SEhD_EVENT_CHN at all. 

• If Queue is true, and If an event is sent to the event channel by 
SEND EVEIsrr C>H tne send EVENrr_CHN call succeeds and a call to 
WAlTlEVENfTjDHN receives the event thus dequeuing the exception. 
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5.7.3 ENABLE_EXce> Exception Management System Call 

ENABLE_EXCEP (Var ErrNuii: Integer; 

Var ExDep-naHiB:t_ex_name) 

ErrNum: Error Irelicator 

Excep_Naine: Name of exception to be enabled 

ENABLE_EXCEP causes an exception to be handled again. Since the 
Operating System automatically disables an exception when its exception 
handler is entered (see DISABLE_EXCEP), the exception handler should 
explicitly re-enctole the exception before it returns to the process. 
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5.7.4 INFO.EXCEP Exception Management system Call 

INFO.EXCEP (Var ErrNuni:Integer; 

Var Excep_Hanie:t_ex_nanie; 
Var EXDepjStatus:tjBx_sts) 

ErrNum: Error indicator 

Excep Nane: Name of exception 
Excep^Status: Status of exception 

IhFO_EXCEP returns information about the exception specified by 
ExcepJMame. The parameter Excep_Status is a record containing information 
about "the exception. This record contains: 

t ex_sts = RECORD (• exception status •) 

Ex_occurred_f:Boolean; ("exception occurred flag ») 
Ex state :t ex state; (• exception status *) 

NiinLexcep:Ihteiger;(*no. of exceptions queued *) 
Hdl adr:Longadr; ("exception handler's address *) 
END; ~" 

Once Exjoccurredjf has been set to true^ only a call to FLUSH_EXCEP can 
set it to"false. 



5-14 



operating System Reference ManuaJ Exertions and Events 

5.7.5 SlGNAL_EXce> ExcepUon Management System Call 

SIGNAL_EXCEP (Var ErrNum-.Integer; 

Var Excep_Nanie:t exjiame; 
Var E)ccep_Data: tjBXjdata) 

ErrNum: Error indicator 

Excep_name: Name of exception to be signaled 

Excep_Data: Information for exception handler 

A process can signal the occurrence of an exception by calling 
SIGNAL_EXCEP. The exception handler associated with Excep_Nanne is 
entered. It is passed ExcepJData/ a data area containing information about 
the nature and cause of the exception. The structure of this information area 
is: 

array[0..slzejexdata] of Longlnt 

SIGN/^L_EXCEP can t)e used for user-defined exceptions and for testing 
exception handlers defined to handle system-defined exceptions. 
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^7 A FLUSH_EXCEP Excepuon Management system Call 

FLUSHJEXCEP (Var ErrNuni:Integer; 

Var Excep_Name:tjex_naine) 

ErrNum: Error Indicator 

Excep_Nanie: Nane of exception whose queue is flushed 

FLUSH_EXCEP Clears out the queue associated with the exception 
Excep_Name and resets its "exception occurred" flag. 
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5.8 Event Management System Calls 

This section describes all the Operating System calls that pertain to event 
management A summary of all the Operating System calls can be found In 
Appendix A. The following special types are used in event management calls: 

Pathname = STRIN6[255]; 
T_ex_naiiie = STOING[16]; 
T_chn_sts = Record 

chn_type : chnjclnd; 
nura_events ; integer; 
open_recv : Integer; 
open_send : integer; 
ec_name :pathname; 
end; 
chn_klnd = (i«it_ec^ call_ec); 
T_ieitlist = Record 

length -.integer; 

refnumcarray [0..10] of integer; 
end; 
P_r_eventdlK = "rjeventtilk; 
R_eventdlk = Record 

event_header : t_eheader; 
event_text : t_event_text; 
end; 
T_eheader = Record 

sendjjid : longint; 
event_type : longint; 
end; 
T_event_text = array [0..9] of longint; 
P_s_eventdlk = *s_eventDlk; 
SjBv/entblk = T_event_text; 
TiiiBstiBp_interval = Record 

sec: longint; 
mseczO. .999; 
end; 
TimB_rec = Record 

year: integer; 
day:1..366; 
hour: -23.. 23; 
minute: -59.. 59; 
second :0.. 59; 
msec :0.. 999; 
end; 
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5.8.1 MAKE_EVEhfr_CHN Event Management synem call 

MAKE_EVENTJDHN (Var EriNuTO: Integer; 

Var Event_cnn_Naine:Pathname) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

MAKE_EVENTjCHN creates an event channel with the name given in 
Event_Chn_NamR The name must be a File System pathname; it cannot be 
null. 
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5.a2 KILL JEVEI^_CHN Event Management system call 

KILL_EVENT_CHN (Var EriNum: Integer; 

Var Event_Chn_Name:Pathnaine) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

To delete an event channel, call KILL_EVENT_CHN. The actual deletion is 
delayed until all processes using the event channel have closed it. In the 
period between the KILL_EVENT_CHN call and the channel's actual deletion, 
no processes can open it. A channel can be deleted by any process that 
knows the channel's name. 
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5.8.3 CPEN_EVENT_CHN Event Management System Call 

0PEN_EVENT_C3HN (Var ErrNum:Integer; 

Var Event_Chn_Name : Pathname; 
Var Refnum: Integer; 

Excep_NanB : tex name; 

Receiver : Boolean) 

ErrNum: Error indicator 

Evenl_Chn_Name: Pathnane of event channel 
RefNum: Identifier of event channel 

Excep_Nafne: Exception name, if any 

Receiver: Access mode of calling process 

CPEN_EVENT_Ofvl opens an event channel and defines its attributes from the 
process point of view. RefNum is returned by the Operating System to be 
used in any further references to the channel. 

Event_crn_Name determines whether the event channel is locally or globally 
defined. If it is a null string, the event channel is locally defined. If 
Event_Chn_Name is not null, it is the File System pathname of the channel. 

ExcepJName determines whether the channel is an event-wait or event-call 
channel. If it is a null string, the channel is of event-wait type. Otherwise, 
the channel is an event-call channel and Excep_hteme is the name of the 
exception that is signaled when an event arrives in the channel. Excep,_Name 
must be declared before its use in the OPENJEVENTjCHN call. 

Receiver is a Boolean value indicating whether the process is opening the 
channel as a sender (Receiver is false) or a receiver (Receiver is true). A 
local channel (one with a null pathname) can be opened only to receive 
events. Also, a call-type channel can only be opened as a receiver. 
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5A4 CLOSE_EVENT_CHN Event Management System Call 

CL0SE_EVENTJCHN (Var ErrNum: Integer; 
RefNum: Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be closed 

CLOSE_EVENT_CHN Closes the event channel associated with ReflMum. Any 
events queued in the channel remain there. The channel cannot be accessed 
until it is opened again. 

If the channel has previously been killed with KILL_EVENT_CHN^ you cannot 
open it after it has been closed. 

If the channel has not been killed, it can be opened by (]PEN_EVENT_CHN. 
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5.8.5 lhFO_EVENT_CHN Event Management System call 

INFO_EVENT_CHN (Var ErrNum: Integer; 
RefNum: Integer; 
Var Chn_Info:t_chn_sts) 

ErrNum: Error indicator 

RefNum: Identifier of event channel 

Chn_Info: Status of event channel 

INFO_EVENT_CHN gives a process information about an event channel. The 
Operating System returns a record^ Chnjnfo, with information pertaining to 
the channel associated with Ref^4um. 

The definition of the type of the ChnJnfO record is: 

t_chn_sts = 

RECORD (* event channel status *) 

Chn_type:Chn_kind; (* «pait_ec or call_ec *) 
NumjBvents: Integer; (* nuntoer of queued events ») 
Open_recv: Integer; (* number of processes reading channel *) 
Open_send: Integer; (* no. of processes sending to this 

channel *) 
Ecjiame: pathname; (* event channel name *) 
END; 
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5.8.6 WAIT_EVENT_CHN Event Management System Call 

l!AIT_EVENT_CHN (Var ErrNum: Integer; 

Var »ait_List:t_waitllst; 
Var Ref Mum: Integer; 

Event_Ptr :p_r_eventdlk) 

ErrNum: Error indicator 

Wait_List: Record with array of event channel refnums 

RefNum: Identifier of channel that had an event 

Event_Ptr: Pointer to event data 

WAITJEVENTjCHN puts the calling process In a waiting state pending the 
arrival of an event in one of the specified channels. Wait_List is a pointer to 
a list of event channel identifiers. When an event arrives in any of these 
channels, the process is made ready to execute. RefNum identifies which 
channel got the event, and Event_Ptr points to the event itself. 

A process can wait for any Boolean combination of events. If it must wait 
for any event from a set of channels (an CR condition), it should call 
WAIT_EVENT_CHN with WaitJList containing the list of event channel 
identifiers. If, on the other hand, it must wait for all the events from a set 
of channels (an ATO condition), then for each channel in the set, 
WAIT_EVENT_CHN Should De called with Wait_Llst containing just that 
channel identifier. 

The structure of t_waiUist is: 

RECORD 
Length: Integer; 
Refnuro:Array[0..size_waitllst] of Integer; 

END; 

Event_Ptr is a pointer to a record containing the event header and the event 
text. Its definition is: 

PjrjBventblk = *r_eventblk; 
RjBventblk = Record 

event_header : t_eheader; 

event_text : t_event_text; 
end; 
T_eneader = Record 

send_pid : longint; 

event_type : longint; 
end; 
T_event_text = array [0. .9] of longint; 

Send_pid is the process id of the sender. 
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Currently^ the possible event type values are: 

1 - Event sent by user process 

2 - Event sent by system 

When you receive the SYS_SCN_TERM event the first longint of the event 
text contains the termination cause of the son process. The cause is same as 
that given in the sys_TERMINATE exception given to the son process. The 
rest of the event text can be filled by the son process. 

If you call WAIT_EVENT_CHN on an event-call channel that has queued 
events, the event is treated just like an event in an event-wait channel. If 
WAIT_EVENT_CHN is called on an event-call channel that does not have any 
queued events, an error is returned. 
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5.8.7 FLUSH_EVENT_CHN Event Management system call 

FLUSH_EVENT_CHN (Var ErrNufR: Integer; 
RefNum: Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to de flushed 

FLUSH_EVENTjCHN Clears out the specified event channel. All events 
queued in the channel are removed. If FLUSH_EVENT_CHN is called dy a 
sender, it has no effect. 
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5.8.8 SEhC)_E\CNT_CHN Event Management system Call 

SEND_EVENT_CHN (Var ErrNum : Integer; 
RefNum:Int^r; 
Event_Ptr :p_s_eventblk; 
Interval :TlinBstinp_interval; 
Clktiine : Tiine_rec) 

ErrNum: Error indicator 

RefNum: Channel for event 

Event_Ptr: Pointer to event data 

Interval: Timer for event 

Clktime: Time data for event 

SEND_EVENT_CHN sends an event to the channel specified by RefNum. 
Event_Ptr points to the event that is to be sent. The event data area 
contains only the event text; the header is added by the system. 

If the event is of the event-wait type, the event is queued. Otherwise the 
Operating System signals the corresponding exception for the process receiving 
the event. 

If the channel is opened by several senders, the receiver can sort the events 
by the process identifier, which the Operating System places in the event 
header. Alternatively, the senders can place predefined identifiers, which 
Identify the sender, in the event text. 

The Interval parameter indicates whether the event is a timed event. 

NOTE 

Timed events will not be supported in future releases of the Operating 
System. The Interval and Clktime parameters will be ignored in future 
releases. If you want your software to be upward-compatible, always 
set both fields of the Interval parameter to zero. 



Timestmp_interval is a record containing a second and a millisecond field. If 
both fields are 0, the event is sent immediately. If the second given is less 
than 0, the millisecond field is ignored and the Time_rec record is used. If 
the time in the Tlme_rec has already passed, the event is sent immediately. 
If the millisecond field is greater than 0, and the second field is greater than 
or equal to 0, the event is sent that number of seconds and milliseconds from 
the present 

A process can time out a request to another process Xi^^ sending itself a timed 
event and then waiting for the arrival of either the timed event or an event 
indicating the request has been served. If the timed event is received first, 
the request has timed out. A process can also time its own progress by 
periodically sending itself a timed event through an event-call event channel. 
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5.9 Clock System Calls 

This section describes all the Operating System calls that pertain to the clock. 
A summary of all the Operating System calls can be found in Appendix A. 

The following special types are used in clock calls: 

Tiinestn|)_lnterval = Record 

sec:longlnt; 
msec :0.. 999; 
end; 
Tiine_rec = Record 

year: integer; 
day:1..366; 
hour: -23.. 23; 
minute: -59. .59; 
second :0.. 59; 
msec:0..999; 
end; 
Hour_range = -23.. 23 
Minutejrange = -59.. 59; 
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5.9.1 DELAY_TIME Clock System cau 

OELAY_nME (Var ErrNuni: Integers- 
Interval : TlniBStiip_interval; 
ClktinerTlmejrec) 

ErrNum: Error indicator 
Interval: Delay timer 
Clktime: Time information 

DELAY_TIME Stops execution of the calling process for the number of seconds 
and milliseconds specified in the Interval record. If this time period is zero^ 
DELAYJTIME has no effect If the period is less than zero, execution of the 
process is delayed until the time specified by Clktime. 
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5.9^ GET_TIME Clock system call 

GET_nME (Var ErrNura: integer; 

Var Sys_Tiiie:Tifne_rec) 

ErrMufn: Error Indicator 
Sys_Ti(ne: Time information 

GETJTTME retums the current system clock time in the record Sys_Tlnie. The 
msec field of Sys_Time always contains a zero on return. 
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5.9.3 SETJL0CAL_TIME_DIFF ciock System call 

SET_LOCAL_nME_DIFF (Var ErrNUTO: Integer; 

Hoiir:Hour_range; 
Minute : Mlnutejrange) 

ErrNum: Error indicator 

Hour: Number of hours difference from the system clock 

Minute: Number of minutes difference from the system clock 

SET_LCK:al_TIME_DIFF informs the Operating System of the difference in 
hours and minutes between the local time and the system clock. Hour and 
Minute can be negative. 
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5.9.4 C0NVERT_TIME Clock System cau 

CONVERT_nME (Var ErrNum: Integer; 

Var Sys_Tiine:TimB_rec; 
Var Local_Time:TlmB_rec; 
To_Sys:Boolean) 

ErrNum: Error indicator 

Sys_Tiine: System clock time 

Local_Tlme: Local time 

To_Sys: Direction of time conversion 

CCINVERT_TIME converts Between local time and system clock time. 

To_Sys is a Boolean value indicating in which direction the conversion is to 
go. If To_Sys is true, the system takes the time data in Local_Time and puts 
the corresponding system time in Sys_Time. If TojSys is false, the system 
takes the time data in Sys_TIme and puts the corresponding local time in 
LocaljTlme. Both time data areas contain the year, month, day, hour, minute, 
second, and millisecond. 
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6.1 Configuration System Calls &-1 

6.1.1 CARDS_EQUIPPED 6-2 

6.1.2 GET_CONFIG NAME 6-3 

6.1.3 0S800TVDL ...7. 6-4 
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Every Lisa system Is ccMiflgured using tjm Preferences tool. Preferences 
places the configuration state of the system in a special part of the system's 
memory called parameter rmmory. Although parameter memory is not 
contained on a disK^ it is supplied with battery power so that the contents are 
kept even when the system is turned off. The batteries are charged as long 
as the Lisa is plugged in, even if the unit is powered off. If line power is 
lost, the batteries will keep parameter memory secured for several hours. In 
addition, every time parameter memory is changed, a copy of the new data is 
made on the boot disk. If the contents of parameter memory are lost, this 
disk copy is automatically restored to parameter memory. 

Since the devices actually connected may differ from the configuration stored 
in parameter memory, three calls are provided that allow programs to request 
information about the configuration of the system. 

NPTE 

Configuration System Calls will be changed in future releases of the 
Operating System. Do not use these calls if you want your software to 
be upward-compatible. 



6.1 Configuration system Calls 

This section describes all the Operating System calls that pertain to 
configuration. A summary of all the ojjerating System calls can be found In 
Appendix A. Special data types used by configuration calls are defined along 
with the calls. 
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&1.1 C7^R0S_EQLflPPED configuration System c^l 

CARDS.EQUEPPED (Var ErrNuiizInteger; 

Var In_Slot:Slotjarray) 

ErrNum: Error code 

In_Slot: Identifies the types of cards configured 

This call returns an array showing the types of cards which are in the various 
card slots. 

The definition of Slot_anay is: 

slotjarray = array [1..3] of canrtypes; 

where: 

card_types » (nojcartt 

applejDant 
nj»rt_car0, 
net_cant 
laserjcard); 
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hX2 GET_CXlNFIQJslAI^ Configuration System CaU 

GETJXJNFIGJWt (Var Ermun: Integer; 
Devpostn:Tports; 
Var Oevnanie:E_Name) 

Ermum: Error code 

Devpostn: A port identifier 

Devname: Tne name of the device attached to the port 

This call returns the name of the device configured at the port given in 
Devposta See OSBCorva- for the definition of Tports. Type E_Name is 
defined as: 

E^NaWB = STRING [32]; 
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6.13 GSBOcnva. cormguration system call 

OSBOCnvQL (Var Entiiiii:lnteger) : iports 

ErrNum: Error code 

Tports: Identifies the port to which the boot volume is attached 

OSBCJOTVDL is a function that returns the identifier for the port attached to 
the boot voluma This port might not be the port configured for the boot 
volume^ since it is possible for the user to override the default boot. Note 
that the port identifier is not the same as the device name. You can use 
GETjCONFlGJMAME to find out the name of the device attached to the port 

Tports Is a set that has this definition: 

Tports - (uppertvig, lonertvig, parallel, 
slotll, slotl?, slotl3, slotu, 
slot21^ slotz?, slot23. slot24, 

SlOt31^ SlOt32, SlOt33, SlOt34, 

seriala, serialb, malnjconsole, altjconsole, 
tjBouse, t_speaker, tjextral, t_extra2^ t_extra3); 



6-4 



Appendixes 



A Gpeiating System Interface UWt A-1 

B System-Reseived Exception Names B-l 

C System-Reserved Event Types C-l 

D Error Messages D-1 

E FS JNFO Fields E-1 



29-0422-A 



Appendix A 
Operating System Interface Unit 



UNIT syscall; 
INTRINSIC; 

INTERFACE 

CONST 

maxjename = 32; 
inax_pathnanie = 255; 
inax_label_slze = 128; 
len_exname = 16; 
sizejexdata = 11; 



sizejBtext = 9; (^ 
slze_i»aitllst = 10; 



(* system call definitions unit *) 



i* maxinuR length of a file system object name 
(« maximum length of a file system pathname 
(* maximum size of a file labels in bytes 
(« length of exception name 
(« 4d bytes^ exception data block should have the 
same size as rjeventblk^ received event block 

event text size - 40 bytes 

size of wait list - should be same as reqptr_list * 



(* exception kind 
call_term = 0; 
ended = 1; 
self .killed = 2; 
killed = 3; 
f thr_term = 4; 
bad_syscall = 5; 
badjermum = 6; 
swapjBiTor = 7; 
stkjoverf low = 8; 
datajDverf low = 9; 
parityjerr = 10; 



definitions for 'SYS.TERHINATE' exception 
process called terminate j)rocess 
process executed 'end' statement 
process called kill_process on self 
process vas killed by another process 
process's father is terminating 
process made invalid sys call - subcode bad 
process passed bad address for ermum parm 
process aborted due to code swap-in error 
process exceeded max size (+T nnn) of stack 
process tried to exceed max data space size 
process got a parity error while executing 



def_div_zero = 11; (* default handler for div zero exception was called 

def_value_oob = 12; (* " for value cob exception 

defjovf w = 13; (* " for overflow exception 

defjrwdjcey = 14; (* " for NMI key exception 

defjrange = 15; <* " for 'SYSJ/ALUEJDOB' excep due to value range err 

def_str_index = 16; (* " for 'SYS_VALUE_O0B' excep due to string index err *) 
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Dus error = 21; 


(* dus error occurred ' 


addr error » 71; 


(* address error occurred ' 


illgLinst = 23; 


(* Illegal instruction trap occurred ' 


priv violation = 24; (* privilege violation trap occurred ' 


line 1010 := 26; 


(* line 1010 enulator occurred ' 


line_llll = 27; 


(« line 1111 emulator occurred 


unexpected ex » 29. 


(* an unexpected exception occurred ' 


div zero =» 31; 


(« exception kind definitions for hardware exception ' 


value ood = 32; 




ovf • - 33; 




nmljcey = 34; 




value range = 35; 


(* excep kind for value range and string index error ' 


str_lndex = 36; 


(* Note that these two cause 'SYS VALUE OUB' excep 


(*DEVICE_CGNTROL functions*) 


dwParlty = 1; 


(*RS-232*) 


dvOutDTR » 2: 


(*RS-232«) 


dvOutXON = 3; 


(*RS-232») 
(«RS-232«) 


dvOutOelay » 4; 


dvBaud = S; 


(*R8-232») 


dvlnlteit - 6; 


(-RS-23?, CMNSOLE*) 


dvlnOTR = 7; 


(*RS-232*) 


dvInXQN » 8; 


(*RS-232») 


dvTypeand = 9; 


(•RS-232*) 


dvOiscon > 10; 


(*RS-232«) 


dvOutNoHS = 11; 


(*RS-232«) 


dwErrStat = 15; 


("PROFILE*) 


dvGetEvent = 16; 


("CONSOLE*) 


dvflutoLF = 17; 


(*RS-232^ CONSOLE, PARALLEL PRINTER*) (*not yet*) 


dvOlskStat = 20; 


("DISKETTE, PROFILE*) 


dvDiskSpare » 21; 


(*oiskette;, profile*) 


TYPE 




pathnanie = string [ii«x_patrwianie]; 


e name » string [rbx enane]; 


nanestrlng ^ string [20]; 


procinfoRec » record 


progpathnaRie : pathname; 


global Id 


longint; 


fatner_id 


longlnt; 


priority 


. 1..255; 


state 


(pactlve, psuspended, pwalting); 


data in 


txx3lean 



) 
) 
) 
) 
*) 



end; 
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Tdstype = (ds_sharecL cls_private); (* types of data segments *) 

dsirrfoRec = record 

inein_size : longint; 

disc_si2e: longint; 

nuiit)_open : Integer; 

Idsn : Integer; 

boundF ; boolean; 

presentF : boolean; 

creatorF : boolean; 

rwaccess : boolean; 

segptr : longint; 

volname: e_nanie; 
end; 



t_ex_name = string [len_exnaine]; 

longadr = "longint; 

t_ex_state » (enabled, queued^ ignored); 

p_ex_data = "t_ex_data; 

t_ex_data = array [0..size_exdata] of longint; 

t_ex_sts = record 

ex_occurred_f : boolean; 

ex_state : t_ex_state; 

nura_excep : integer; 



ndl_adr 

end; 

P_env_blk 

env_blk = 

PC : 

sr : 

dO : 

dl : 

d2 : 

d5 : 

d4 : 

d5 : 

d6 : 

d7 : 

aO : 

al : 

a2 : 

a3 : 

a4 : 

as : 

a6 : 

a7 : 

end; 



longadr; 

= '*env_blk; 

record 

longint; 

integer; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 

longint; 



(* exception name 
(* exception state 

(* exception data blk 

(* exception status 
(* exception occurred flag 
(* exception state 
(* nuntoer of exceptions q'ed 
(* handler address 



(* environment block to pass to handler 

(* program counter 

(* status register 

(* data registers 0-7 



(* address registers 0-7 
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(* terminate exception data block 



p_tenn_ex_data = *term_ex_clata; 
term_ex_clata = record 

case excep_kind : longint of 

call_ternL 

enc^^ 

self_killed, 

killed, 

fthr_terut 

t)ad_syscall, 

bad_ermuiit 

si»^_error, 

stk_overfloi», 

data_overflo», 

parity_err : (); (* due to process termination 



lHQLlnst. 
priv_violation, 

line_1010, 

llne_llll, 

ctef_div_zero, 

def_value_ooD. 

def_ovfw, 

def_nmi_key 



(* due to illegal instruction, privilege 

violation *) 

(* due to line 1010, 1111 emulator *) 



end; 



(* terminate due to default handler for hardware 
exception *) 

: (sr : integer; 

pc : longint); (* at the time of occurrence *) 

def_range, 

def_str_index (* terminate due to default handler for 

•SYS_VALUE„008' excep for value range or string 
inctex error *) 

: (value_check : Integer; 
upper_bound : integer; 
lo«er_bound : integer; 
return jK) : longint; 
caller_a6 : longint); 
t)us_error, 

addr_error (* due to bus error or address error *) 
: (fun_field : packed record (* one integer *) 

filler : 0, .$7ff; (* 11 bits *) 

r_«_f lag : boolean; 
i_n_f lag : boolean; 
fun code : 0..7; (* 3 bits «) 
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access_atlr : longlnt; 
inst_register : integer; 
sr_error : Integer; 
pc_error : longint); 
end; 

p_hard_ex_cJata = "hardjexjdata; 
hard_ex_data = record 

case excep_klnd : longlnt of 

div_zero, value_oob, ovf w 

: (sr : Integer; 

pc : longlnt); 

valiie_range, str_lndex 

: (valiie_check : Integer; 

upperjwund : Integer; 

lo«er_bound : Integer; 

return jx; : longlnt; 

caller_a6 : longlnt); 
end; 



(« hardware exception data block 



accesses - (dread, dwite, append, private, global_refnum); 

inset = set of accesses; 

iomode = (absolute, relative, sequential); 

UIO = record (^unique id*) 

a«b: longint 
end; 



tiinBstiBp_interval = record 

sec : longint; 

msec : 0..999; 
end; 



(• time interval *) 

(* nunfcer of seconds *) 

(* nuraber of milliseconds within a second *) 



lnfo_type = (device_t, voluroB_t, objectj;); 

devtype = (diskdev, pascalbd, seqdev, bitbkt, non_io); 

filetype = (undefined, fDDFfile, rootcat, freelist, badblocks, sysdata, 

spool, exec, usercat, pipe, bootf lie, swapdata, swapcode, ramap, 

userfile, killedodject); 

entrytype= (enptyentry, catentry, llnkentry, flleentry, plpeentry, ecentry, 
killedentry); 
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f s_lrTfo = record 
name : e_name; 
dlr j)atn : pathname; 
machlne_id : longint; 
f sjoverhead : Integer; 
result_scavenge : integer; 
case otype : Inf o_type of 
devlce_t, volumB_t: ( 
lochannel : Integer; 
devt : devtype; 
slot_no : integer; 
f s_size : longint; 
vol_size : longint; 
blockstructured, mounted : ixx)lean; 
opencount : longint; 

privatedev, remote, locKeddev : Ixnlean; 
mountjpending, unmount_pending : txnlean; 
volname, password : ejiame; 
fsversion, volnum : integer; 
volid : UID; 
Dackup_volid : UID; 

blocksize, datasize, clustersize, filecount : integer; 
label_size : integer; 
f reecount : longint; 
DTVa D7€C. D7VB, DTVS : longint; 
masterjDopy_id, copy_tnread : longint; 
oy/ermount_stanp : UID; 
boot_code : integer; 
r)oot_environ : integer; 
privileged, witej)rotected : boolean; 
master, copy, copy_f lag, scavenge_f lag : boolean; 
vol_left_mounted : boolean ); 

object_t : ( 

size : longint; 

psize : longint; (* physical file size in bytes *) 

ipsize : integer; (* logical page size in bytes for this file *) 

ftype : filetype; 

etype : entrytype; 

DTD, DTA, DT!t DTB, DTS : longint; 

refnuro : integer; 

f mark : longint; 

acmode : mset; 

nreaders, nwriters, nusers : integer; 

fuid : UID; 

user_type : integer; 

user_subtype : integer; 
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systefli_type : Integer; 
eof, safety_on, kswitch : boolean; 
private, locked, protected, njaster_f lie : boolean; 
file_scavenged, file_closed_by_OS, file_left_open: boolean) 
end; 

dctype = record 

dcversion : integer; 

decode : integer; 

dcdata : array [0..9] of longint; 
end; 



t_i»aitlist = record 

length : integer; 

refnum : array [0..size_<»aitlist] of integer; 
end; 



(* user/driver defined data 
(* wait list 



tjBheader = record 

send_pid : longint; 
event_type : longint; 

end; 



(* event header 

(* sender's process id 

(* type of event 



t_event_text = array [0..slze_etext] of longint; 
p_r_eventblk = *r_eventblk; 
r_eventblk = record 

event_header : t_eheader; 

event_text : t_event_text; 
end; 

p_s_event51k = *s_eventblk; 
s eventblk = t event text; 



timB_rec = record 

year : integer; 

day : 1..366; 

hour : -23.. 23; 

minute : -59, .59; 

second : 0..59; 

msec : 0..999; 
end; 



(* Julian date *) 
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chnjclnd = (leitjec, calljBc); 

t_chn_8ts = record (* channel status *) 

cnn_type : cTftklnO; (* cfiannel type 

numjevents : Integer; (* nuitoer of events queued 

openjrecv : integer; (* nunber of opens for receiving * 

open_send : Integer; (* nunber of opens for sending 

ecjiame : pathnaRe; (* event channel name * 

end; 

hour_range = -23. .23; 
mlnute.range = -59. .59; 

{configuration stuff: } 

tports " (uppertvig, lowertvig, parallel^ 
slotlL slotlZ, slotl3, slotu. 

SlOt21, SlOt2^, SlOt23, SlOt24. 

SlOt3L SlOt32, SlOt33, SlOt34. 

seriala^ serialb^ mainjconsole^ altjxmsole, 

tjmuse^ t_speaker, tjextral, t_extra2, t_extra3); 

card_types = (nojcant applejcant njwrtjcant netjoant laserjcard); 

slotjarray = array [1..3] of card_types; 

{ Lisa Office System parameter memory type } 

pHfiyteUhique » -128.. 127; 

pMenf^ = array [1.. 62] of pm^teUnique; 

(* File System calls «) 

procedure nAKE_FILE (var ecode: Integer; var path:pathname; 
latel.slze : Integer); 

procedure nAKE_PlPE (var ecode:lnteger; var path:pathname; 
label_slze : Integer); 

procedure hAKEjCATALOG (var ecode: integer; var path: pathname; 
latel_slze : integer ); 

procedure mKEjLiNK (var ecode: integer; var path^ ref :pathname; 
label_size : integer); 
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procedure KILL_OBJECT (var ecode: Integer; var path: pathname); 

procedure UNKILL_FILE (var ecode: Integer; refnum: integer; var 
new_name : e_naiiie); 

procetXire OPEN (var ecode: integer; var pathipatmame; var refrwm: integer; 
manip:inset); 

procedure CLOSE_OBJECT (var ecode: integer; refnum: integer); 

procedure READ_E)ATA (var ecode: Integer; refnum: integer; data_addr:longint; 
count :longint; var actual :longint; niode:iomode; 
offset :longint); 

procedure WRITE_DATA (var ecode:integer; refnumcinteger; data_addr:longlnt; 
count:longlnt; var actual:longint; mode:iomode; 
offset:longint); 

procedure FLUSH (var ecode: integer; refnum: integer); 

procedure LOOKUP (var ecode:integer; var path:pathname; var 
attributes:fs_info); 

procechjre IWQ (var ecode: integer; refmm: integer; var refinfo:fs_info); 

procedure ALLCKIATE (var ecode:inte^r; refrimiinte^r; conti^jous:boole»i; 
count:longint; var actual:longint); 



procedure TRUNCATE (var ecode:integer; refnum:integer); 

procedure COMPACT (var ecode:integer; refnuntinteger); 

procedure RENAriE_ENTRY ( var ecode: integer; var path: pathname; var 
ne«name«_naine ); 

procedure f^AD_L/^:L ( var ecode:integer; var path:patrviame; 

data_addr:longint; count:longint; var actual:longint ); 

procedure WRITE_LABEL ( var ecode:integer; var path:pathname; 

data_addr:longint; cot«it:longint; var actiKil:longint ); 

procedure MOUNT ( var ecode: integer; var vname : ereine; var passnurd : 
e_name ;var devname : e_name); 

procedure UNMOUNT ( var ecode: integer; var vname : e_name ); 
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procedure SET_WORKING_DIR ( var ecode: Integer; var path -.pathname ); 

procedure GET_WORKING_DIR ( var ecode -.integer; var path: pathname ); 

procedure SETSAFETY (var ecode rlnte^r; var path :patmame;on_off: boolean ); 

procedure DEVICE_CONTROL ( var ecode -.integer; var path: pathname; 
var cparm : dctype ); 

procedure RESET_CATAL06 (var ecoderinteger; var pathrpathname); 

procedure GET_NEXT_ENTRY (var ecoderinteger; var prefix, entry:e_name); 

procedure SET_FILE_IhFO (var ecode :integer; refnurarinteger; f si:fs_lnfo); 

(* Process Management system calls *) 

function riy_ID:longint; 

procedure Info_Process (var ermumtlnteger; proc_id:longlnt; var 
proc_info:procinfoRec); 

proceckjre Yield_CPU (var errrxwtinte^r; to_any:booleai); 

procedure SetPriority_Process (var errmmlnte^r; proc_id:lmgint; 
new_prlorlty:integer); 

procedure Suspend_Process (var ermufit Integer; proc_id:longint; 
susp_fanily-Jxx)leai); 

procedure Actlvate_Process (var errrwjitinteger; proc_id:longint; 
act_f ami lyiboolean); 

procedure Kiii_Process (var errmminteger; proc_id:ionglnt); 

procedure Terminate_Process (var ermuntinteger; event_ptr:p_s_eventblk); 

procedure riake_Process (var errnuntinteger; var proc_id:longint; var 
progf ileipathname; var entrynane:nanestring; 
evnt_chn_refnum:integer); 
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(* Memory Management system calls ») 

procedure make_dataseg(var errnum: integer; var segname: pathname; mem_slze, 
disc_size: longint; var refnum: Integer; var segptr: 
longlnt; idsn: integer; dstype: Tdstype); 

procedure kiil_dataseg (var ermumrinteger; var segname:pathname); 

procedure open_dataseg (var ermum:integer; var segname:pathname; var 
refnumcinteger; var segDtrilwigint; Idsniinteger); 

procedure close_dataseg (var ermuntinteger; refnum: integer); 

procedure slze_dataseg (var errnuntinteger; refnumrinteger; 

deltaBiiemslze:longint; var newmemsize;longint; 
deltadiscslze: longlnt; var newdiscslze: longint); 

procedure info_dataseg (var ermumrlnteger; refnumrinteger; var 
dsinfo:dsinfoRec); 

procedure setacGess_dataseg (var errnum: integer; refrwrncinte^r; 
readonly:tx>olean); 

procedure unbind„dataseg (var ermuntinteger; refnum:integer); 

procedure blnd_dataseg(var errnumrinteger; refnum:integer); 

procedure info_ldsn (var ermuitinteger; Idsn: integer; var refnum: integer); 

procedure flusn_dataseg(var errnum: integer; refnum: Integer); 

procedure mem_info(var errnum: integer; var swapspace, dataspace, 
cur_codesize^ max_codesize: longint); 

procedure info_a(fclress(var errnum: integer; address: longint; var refmm: 
integer); 

(* Exception Management system calls *) 

procechire declare_exKep_hdl (var ermuitinteger; var excep_n<^nB:t_ex_nane; 
entry jx)int:longadr); 

procedure dlsadle_excep (var errnufftinteger; var excep_name:t_ex_name; 
qto^boolean); 



A-ll 



qperatJng System Reference /^tantjal QperaUf^ System Interface Unit 

procedure enable_excep (var ermuntlnteger; var excep_nanie:t_ex_naine); 

procedure slgnal_excep (var ermuntlnteger; var excep_nane:t_ex_name; 
excep_data:t_ex_clata); 

procedure lnfo_excep (var ermuntlnteger; var excep_name:t_ex_name; var 
excep_status:t_ex_sts); 

procedure flush_excep (var ermuntlnteger; var excep_name:t_ex_nanie); 

(» Event Channel management system calls *») 

procedure make_event_chn (var ermuntlnteger; var event_chn_name:pathname); 

procedure klll_event_chn (var ermuntlnteger; var event_chn_name:pathname); 

procedure open_event_chn (var ermuntlnteger; var event_cnn_name:pathname; var 
refnuntlnteger; var excep_name:t_ex_name; 
recelver:tx)olean); 

procedure close_event_chn (var ermuntlnteger; refnuntlnteger); 

procedure lnfo_event_chn (var ermuntlnteger; refntmtlnteger; var 
chn_lnfo:t„cnn_sts); 

procedure »ait_event_chn (var ermuntlnteger; var walt_llst:t_waitlist; var 
refnuntlnteger; event_ptr:p_r_eventblk); 

procedure flush_event_chn (var ermuntlnteger; refnuntlnteger); 

procedure send_event_chn (var ermuntlnteger; refnuntlnteger; 

event_ptr:p_s_eventblk; lnterval:tlmestnp_lnterval; 
clktlme:tlme_rec); 



(» Timer functions system calls •) 

procedure delay_time (var errrwnt Integer; lnterval:timestinp_lnterval; 
clktlnie:tlme_rec); 

procedure get_tlme (var ermuntlnteger; var gmt_tlme:time_rec); 

procedure set_local_tlme_dlff (var ermuntlnteger; hour:hour_range; 
mlnute:mlnute_range); 
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procedure convert_tiine (var ermuntlnteger; var gmt_t inert line_rec; var 
local_tinie:time_rec; tojgmtiboolean); 

{configuration stuff} 

function OSBOOTVOL(var error : integer) : tports; 

procedure GET_C0NFI6_NA^E( var error:integer; devpostn:tports; var 
devname:e_name); 

procedure CARDS_EQUIPPED(var errorrinteger; var in_slot:slot_array); 

IhPLEMENTATION 

procedure MAKE_FILE; externals- 
procedure MAKE_PIPE; external; 
procedure riAKE_CATALOG; external; 
procedure riAKE_LINK; external; 
procedure KILL_OBJECT; external; 
procedure OPEN; external; 
procedure CLOSE_OBJECT; external; 
procedure READ_DATA; external; 
procedure lilRITE_DATA; external; 
procedure FLUSH; external; 
procedure LOOKUP; external; 
procedure INFO; external; 
procedure ALLOCATE; external; 
procedure TRUNCATE; external; 
procedure COTFACT; external; 
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procedure RENAME_ENTRY; external; 
procedure READ_LABEL; external; 
procedure IIRITE_LABEL; external; 
procedure MOUNT; external; 
procedure UNTIOUNT; external; 
procedure SET_WRKING_DIR; external; 
procedure GET_IWRKING_DIR; external; 
procedure SET_SAFETY; external; 
procedure DEVICEJDONTROL; external; 
procedure RESET_CATALOG; external; 
procedure GET_NEXT_ENTRY; external; 
procedure GET_DEV_NAME; external; 

function riy_ID; external; 
procedure Info_Process; external; 
procedure YieldjDPU; external; 
procedure SetPrlority_Process; external; 
procedure Suspend_Process; external; 
procedure Activate_Process; external; 
procedure Kill_Pro(»3S; external; 
procedure Terniinate_Process; external; 
procedure Make_Process; external; 
procedure SchedjDlass; external; 
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procedure m^e_dataseg; e)ctemal; 
procedure klll_dataseg; external; 
procedure open_dataseg; external; 
procedure closejJataseg; external; 
procedure size_dataseg; external; 
procedure Inf ojdataseg; external; 
procedure setacoess_datasec|; external; 
procedure unblndjdataseg; external; 
procedure bindjdataseg; external; 
procedure info_ldsn; external; 
procedure f lush_dataseg; external; 
procedure nieiii_inf o; external; 

procedure declare_excep_hdl; external; 
procedure dlsablejexcep; external; 
procedure enable_excep; external; 
procedure slgnaljBxcep; external; 
procedure lnfo_excep; external; 
procedure f lushjBxcep; external; 

procedure make_event_chn; external; 
procedure klll_event_chn; external; 
procedure open_event_chn; external; 
procedure closejeventjchn; external; 
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procedure inf o_event_crfv external; 
procedure •ait_event_crin; external; 
procedure f lusn_event_cnn; external; 
procedure send_event_chn; external; 

procedure delay_tiine; external; 
procedure get_tiiBB; external; 
procedure set_local_timB_dif f; external; 
procedure convert_tlmB; external; 
procedure set_file_lnfo; external; 
function ENABLED6G0* external; 
function OSBOOTVOL; external; 
procedure GET_CONFIG_NAHE; external; 
function DISK_UKELY; external; 
procedure CARDSJEQUIPPED; external; 
procedure Read_Priein; external; 
procedure iriteJ^Menu external; 
end. 
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SYS_OVERFLOW Overflow exception. Signaled when the TRAPV instruction is 
executed and the overflow condition is on. 

SYS VALUE_OOB Value-out-of-bound exceptioa Signaled when the CHK 

instruction is executed and the value is less than or greater 
than upper bound. 

SYS_ZERO_DIV Division by zero exception. Signaled when the DIVS or DIVU 
instruction is executed and the divisor is zero. 

SYS_TERM1NATE Termination exception. Signaled when a process is to be 
terminated. 
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SYS_SON_TERM "Son terminate" event type. If a father process has created a son 
process with a local event channel this event is sent to the 
father process when the son process terminates. 
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-6081 End of exec file input 

-600a Attempt to reset text file with typed-f ile type 

-6003 Attempt to reset nontext file with text type 

-1885 ProFile not present during driver initialization 

-1882 ProFile not present during driver initialization 

-1176 Data In the object have been altered by Scavenger 

-1175 File or volume was scavenged 

-117a File was left open or volume was left mounted^ and system crashed 

-1173 File was last closed by the OS 

-1146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent boot 

volume 

-1060 Attempt to mount a foreign boot disk following a temporary unmount 

-1059 The bad block directory of the diskette is almost full or difficult to read 

-696 Printer out of paper during initialization 

-660 Cable disconnected during ProFile initialization 

-626 Scavenger indicated data are questionable^ but may be OK 

-622 Parameter memory and the disk copy were both invalid 

-621 Parameter memory was invalid but the disk copy was valid 

-620 Parameter memory was valid but the disk copy was invalid 

-413 Event channel was scavenged 

-412 Event channel was left open and system crashed 

-321 Data segment open when the system crashed. Data possibly invalid. 

-320 Could not determine size of data segment 

-150 Process was created^ but a library used by program has been scavenged and 

altered 

-149 Process was created^ but the specified program file has been scavenged and 

altered 

-125 Sepcif led process is already terminating 

-120 Specif ied process is already active 

- 1 15 Specified process is already suspended 

100 Specified process does not exist 

101 Specified process is a system process 
110 Invalid priority specified (must be 1..225) 

130 Could not open program file 

131 File System error while trying to read program file 

132 Invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get sy sglobal space for new process 

136 Could not set up communication channel for new process 
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138 Error accessing program file while loaaing 

141 Error accessing a library file while loading program 

142 Cannot run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic Library 

144 Program uses an intrinsic unit whose name/type does not agree with the 
Intrinsic Library 

145 Program uses a shared segment not found in the intrinsic Library 

146 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

147 No space in syslocal for program file descriptor during process creation 

148 No space in the shared lU data segment for the program's shared lU globals 

190 No space in syslocal for program file description during List_LibFiles 
operation 

191 Could not open program file 

192 Error trying to read program file 

193 Cannot read protected program file 

194 Invalid program file (incorrect format) 

195 Program uses a shared segment not found in the Intrinsic Library 

196 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

198 Disk I/O error trying to read the intrinsic unit directory 

199 specified library file number does not exist in the Intrinsic Library 

201 No such exception name declared 

202 No space left in the system data area for Declare_Excep_Hdl or 
Signal_Excep 

203 Null name specified as exception name 

302 invalid LDSN 

303 No data segment bound to the LDSN 

304 Data segment already bound to tne LDSN 

306 Data segment too large 

307 Input data segment path name Is invalid 

308 Data segment already exists 

309 Insufficient disk space for data segment 

310 An invalid size has been specified 

311 Insufficient system resources 

312 Unexpected File System error 

313 Data segment not found 

314 Invalid address passed to Info_Address 

315 Insufficient memory for operation 

317 Disk error while trying to swap in data segment 

401 Invalid event channel name passed to Make_Event_Chn 

402 No space left in system global data area for Open_Event_Chn 

403 No space left in system local data area for Open_Event_Chn 

404 Non-block-structured device specified in pathname 

405 Catalog is full in Make_Event_Chn or Open_Event_Chn 

406 No such event channel exists in Kill_Event_Chn 
41 Attempt to open a local event channel to send 
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41 1 Attempt to open event channel to receive when event channel nas a receiver 

413 Unexpected File System error in Open_Event_Chn 

416 Cannot get enough disk space for event channel in open_Event_Chn 

417 Unexpected File System error in Close_Event_Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 Wait_Event_Chn returns empty because sender process could not complete 

422 Attempt to call wait_Event_Chn on an empty event-call channel 

423 Cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of expected 
size 

425 Event channel empty after being unblocked,_Wait_Event_Chn 

426 Bad request pointer error returned in Wait_Event_Chn 

427 wait_List has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected File System error in wait_Event_Chn 

430 Attempt to send to a channel which the calling process does not have open 

431 Amount of data transferred while writing to event channel not of expected 
size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unexpected File System error in Send_Event_Chn 

440 Unexpected File System error in Make_Event_Chn 

441 Event channel already exists in Make_Event_Chn 
445 Unexpected File System error in Kill_Event_Chn 
450 Unexpected File System error in Flush_Event_Chn 

530 Size of stack expansion request exceeds limit specified for program 

531 Cannot perform explicit stack expansion due to lack of memory 

532 insufficient disk space for explicit stack expansion 
600 Attempt to perform I/O operation on non I/O request 
602 No more alarms available during driver initialization 

605 Call to nonconf igured device driver 

606 Cannot find sector on floppy diskette (disk unformatted) 

608 Illegal length or disk address for transfer 

609 Call to nonconfigured device driver 

610 No more room in sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled on floppy 
drive 

614 No disk present in drive 

615 V/rong call version to floppy drive 

616 Unpermitted floppy drive function 

617 Checksum error on floppy diskette 

618 Cannot format, or write protected, or error unclamping floppy diskette 

619 No more room in sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 

625 Scavenger indicated data are bad 

630 The time passed to Delay_Time, Convert_Time, or Send_Event_Chn has 
invalid year 

631 Illegal timeout request parameter 
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632 NO memory available to initialize clock 

634 Illegal timed event id of - 1 

635 Process got unoiocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to Delay_Time or Send_Event_Chn more than 23 days from 
current time 

639 Illegal date passed to Set_Time, or illegal date from system clock in 
Get_Time 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write initiated witn Illegal parameter 

642 Unimplemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 unexpected RS-232 timer interrupt 

648 Unpermitted RS-232 initialization^ or disconnect detected 

649 Illegal device control parameters to RS-232 

652 N-port driver not initialized prior to ProFile 

653 No room in sysglobal to initialize ProFIle 

654 Hard error status returned from drive 

655 Wrong call version to ProFile 

656 Unpermitted ProFile function 

657 Illegal device control parameter to ProFile 

658 Premature end of file wben reading from driver 

659 Corrupt File System header chain found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to ProFile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

67 Bad command response from drive 

671 Illegal length specified (must - 1 on input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 

675 Illegal device control 

680 Wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysglobal to ir iltialize serial driver 

685 Eject not allowed this device 

686 No room in sysglobal to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 Wrong call version to n-port card driver 

690 Wrong call version to parallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysglobal to initialize parallel printer 

694 Unimplemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 
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698 Printer offline 

699 No response from printer 

700 Mismatch between loader version number and Operating System version 
number 

701 OS exhausted i ts internal space during startup 

702 Cannot make system process 

703 Cannot kill pseudo-outer process 
7 04 Cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the File System volume 

708 Hard disk mount table unreadable 

709 Cannot map screen data 

710 Too many slot-based devices 

724 The boot tracks do not know the right File System version 

725 Eitber damaged File System or damaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM.OS is missing 

729 SYSTEM.CONFIG is corrupt 

730 SYSTEM.OS is corrupt 

731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

732 SYSTEM.LLD is corrupt 

733 Loader range error 

754 V</rong driver is found. For instance, storing a diskette loader on a ProFile 

735 SYSTEM.LLD is missing 

736 SYSTEM.UNPACK is missing 

737 Unpack of SYSTEM.OS With SYSTEM.UNPACK failed 

801 lOResult <> on I/O using the Monitor 

802 Asynchronous I/O request not completed successful ly 

803 Bad combination of mode parameters 
806 Page specified is out of range 

809 Invalid arguments (page, address, offset, or count) 

810 The requested page could not be read in 

816 Not enough sysglobal space for File System buffers 

819 Bad device number 

820 No space in sysglobal for asynchronous request list 

821 Already initialized I/O for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to allocate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 
835 Invalid s-file number 

837 Unallocated s-file or I/O error 

838 Map overflow: s-file too large 

839 Attempt to compact file past PEOF 
841 Unallocated s-file or I/O error 
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843 Requested exact f 1 1, but one could not be provided 

847 Requested transfer count is <- 

848 End of file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit number 

854 No free slots in s-list directory (too many s- files) 

855 No available disk space for file nints 

856 Device not mounted 

857 Empty, locked. or invalids-file 

861 Relative page is beyond PECF (bad parameter value) 

864 No sysglobal space for volume bitmap 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number 

868 Bad unit number 

869 unit already mounted (mount)/no unit mounted 

870 No sysglobal space for DCB or MDDF 

871 Parameter not a valid s- file ID 

872 No sysglobal space for s-flle control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 Invalid s-flle ID or s-flle control block 
879 Attempt to postion past LECF 

881 Attempt te read empty file 

882 No space on volume for new data page of file 

883 Attempt to read past LEOF 

884 Not first aute-allocation, but file was empty 

885 Could not update fllesize hints after a write 

886 No syslocal space for 1/0 request 1 ist 

887 Catelog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry Xi^i that name already exists 

891 Catelog is full or is damaged 

892 Illegal name for an entry 

894 Entry not found, or catelog is damaged 

895 Invalid entry name 

896 Safety switeh is on— cannot kill entry 

897 Invalid bootdev value 

899 Attempt to allocate a pipe 

900 invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device 

922 Invalid label size 

926 Pathname invalid orno such device 

927 Invalid label size 

941 Pathname invalid or no such device 

944 Object is not a file 

945 File is not in the killed stete 
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946 Pathname invalid or no such device 

947 Not enough space in syslocal for File System ref db 

948 Entry not found in specified catalog 

949 Private access not allowed if file already open shared 

950 Pipe already in use, requested access not possible or dwrite not allowed 

951 File is already opened in private mode 

952 Badrefnum 

954 Bad refnum 

955 Read access not allowed to specified object 

956 Attempt to position FMARK past LEOF not allowed 

957 Negative request count Is Illegal 

958 Nonsequential access is not allowed 

959 System resources exhausted 

960 Error writing to pipe while an unsatisfied read was pending 

961 Badrefnum 

962 No WRITE or APPEND access allowed 

963 Attempt to position FMARK too far past LEOF 

964 Append access not al lowed in absolute mode 

965 AjDpend access not allowed in relative mode 

966 Internal inconsistency of FMARK and LEOF (warning) 

967 Nonsequential access is not allowed 

968 Badrefnum 

971 Pathname invalid or no sucn device 

972 Entry not found in specified catalog 
974 Badrefnum 

977 Bad refnum 

978 Page count is nonpositive 

979 Not a block-structured device 

981 Bad refnum 

982 No space has been allocated for specified f i le 

983 Not a block-structured device 

985 Badrefnum 

986 No space has been allocated for specified file 

987 Not a block-structured device 

988 Badrefnum 

989 Caller is not a reader of the pipe 

990 Not a block-structured device 

994 Invalid ref num 

995 Not a block-structured device 

999 Asynchronous read was unblocked before it was satisfied 

1 02 1 Pathname invalid or no sucn entry 

1022 No such entry found 

1023 Invalid newname. check for '-' in string 

1024 New name already exists in catalog 

1031 Pathname invalid or no such entry 

1032 Invalid transfer count 

1033 No such entry found 
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1041 Pathname Invalid or no such entry 

1042 Invalid transfer count 

1043 No such entry found 

1051 No device or volume by that name 

1052 A volume is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume just unmounted from 
this Lisa 

1054 The bad block directory of the diskette is invalid 

1 061 No device or volume by that name 

1 062 No volume is mounted on device 

1071 Not a valid or mounted volume for working directory 

1091 Pathname invalid or no such entry 

1092 No such entry found 
1101 Invalid device name 

1121 Invalid device, not mounted, or catalog is damaged 

1128 Invalid pathname, device, or volume not mounted 

1130 File is protected; cannot open due to protection violation 

1131 No device or volume by that name 

1 132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space in sysglobal for open file list 

1 135 Cannot find the open file entry to modify 

1 1 36 Boot volume not mounted 

1 137 Boot volume already unmounted 

1 138 Caller cannot have higher priority than system processes when calling uDd 

1141 Boot volume was not unmounted when calling rbd 

1 142 Some other volume still mounted on the boot device when calling rbd 

1 143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted boot 
volume 

1145 No sysglobal space for bit map to do rbd 

1158 Track -by- track copy buffer is too small 

1 159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power Is already off 

1163 Illegal command 

1 164 Device is not a diskette device 

1 165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1 167 Not a block-structured device 

1168 Device name is invalid 

1169 Could not access device before initialization using default device 
parameters 

1170 Could not mount volume after initialization 

1171 '-' is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 
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1176 Cannot read from a pipe more than half of its allocated physical size 

1 177 Cannot cancel a read request for a pipe 

1178 Process waiting for pipe data got unblocked because last pipe writer closed 
it 

1180 Cannot write to a pipe more than half of Its allocated physical size 

1 181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was satisfied 

1 183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unblocked because the reader closed the 
pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 

1 188 Cannot compact a pipe while it has data wrapped around 

1190 Attempt to access a page that is not allocated to the pipe 

1191 Bad parameter 

1193 Premature end of file encountered 

1196 Something is still open on device—cannot unmount 

1 197 Volume is not formatted or cannot be read 

1 198 Negative request count is illegal 

1 199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 Invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 
1215 Error writing boot track program 

1214 Boot track program file not found 

1215 Cannot write boot tracks on that device 

1216 Could not create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Could not find configuration Information entry 

1219 Could not get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scavenger has detected an internal inconsistency symptomatic of a software 
bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1230 Cannot write consistently to the volume 

1231 Cannot allocate space (Heap segment) 

1232 Cannot allocate space (Map segment) 

1233 Cannot allocate space (SFDB segment) 
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1257 Error reDullding the volume root directory 

1240 Illegal attempt to scavenge a non-OS-formatted volume 

1296 Bad string argument has Deen passed 

1297 Entry name for the object Is invalid (on the volume) 

1298 S-list entry for the oOject is invalid (on the volume) 
1807 No disk in floppy drive 

1820 Write-protect error on floppy drive 

1822 Unable to clamp floppy drive 

1824 Floppy drive write error 

1882 Bad response from ProFile 

1885 ProFile timeout error 

1998 Invalid parameter address 

1999 Badrefnum 

6001 Attempt to access unopened file 

6002 Attempt to reopen a file which is not closed using an open FIB (file info block) 

6003 (Iteration incompatible with access mode with which file was opened 

6004 Printer offline 

6005 File record type incompatible with character device (must be byte sized) 

6006 Bad integer (read) 

6010 Operation incompatible with file type or access mode 

6081 Premature end of exec file 

6082 Invalid exec (temporary) file name 

6083 Attempt to set prefix with null name 

6090 Attempt to move console with exec or output file open 

6101 Bad real (read) 

6151 Attempt to reinitalize heap already in use 

6152 Bad argument to NEW (negative size) 

6153 Insufficient memory for NEW request 

6154 Attempt to RELEASE outside of heap 

operating System Error Codes 

The error codes listed below are generated only when a nonrecoverable error 
occurs while in C^erating System code. 

10050 Request block is not chained to a PCB (Unblk_Req) 

10051 Bld_Req is called with interrupts off 

10100 An error was returned from SetUp_Directory or a Data Segment routine 
(Setup JUInfo) 

10102 Error > trying to create shell (Root) 

10103 Sem„Count> l(Init_Sem) 

10104 Could not open event channel for shell (Root) 

10197 Automatic stack expansion fault occurred in system code (Check_stack) 

10198 Need_Mem set for current process while scheduling is disabled 
(SimpleScheduler) 

10199 Attempt to block for reason other than I/O while scheduling is disabled 
(SimpleScheduler) 

10201 Hardware exception occurred while in system code 

10202 No space left from Sigl_Excep call in Hard_Excep 
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10203 No space left from Sigl_Excep call In Nmi_Excep 
10205 Error from Wait_Event_Chn called In Excep_Prolog 

10207 No system data space in Excep_setup 

10208 No space left from Sigl_Excep call in range error 

10212 Error in Term_Def_Hcil from EnaPle_Excep 

10213 Error in Force_Term_Excep^ no space in Enq_Ex_Data 
10401 Error from close_Event_Chn in Ec_Cleanup 

10582 Unable to get space in Freeze_Seg 
10590 Fatal memory parity error 

10593 Unable to move memory manager segment during startup 

10594 Unable to swap in a segment during startup 

10595 Unable to get space in Extend_MMlist 

10596 Trying to alter size of segment that is not data or stack (Ait_DS_Size) 

10597 Trying to allocate space to an allocated segment (Alloc_Mem) 

10598 Attempting to allocate a nonfree memory region (Take_Free) 

10600 Error attempting to make timer pipe 

10601 Error from Kill_Object of an existing timer pipe 

10602 Error from second Make_Pipe to make timer pipe 

10603 Error from open to open timer pipe 

10604 No syslocal space for head of timer list 

10605 Error during allocate space for timer pipe, or interrupt from nonconfigured 
device 

10609 Interrupt from nonconfigured device 

10610 Error from info about timer pipe 

10611 Spurious interrupt from floppy drive #2 

10612 Spurious interrupt from floppy drive #1, or no syslocal space for timer list 
element 

10613 Error from Read_Data of timer pipe 

10614 Actual returned from Read_Data is not the same as requested from timer 
pipe 

10615 Error from open of the receiver's event channel 

10616 Error from Write_Event to the receiver's event channel 

10617 Error from Close_Event_Chn on the receiver's pipe 
10619 No sysglobal space for timer request block 

10624 Attempt to shut down floppy disk controller while drive is still busy 
10637 Not enough memory to initialize system timeout drives 
10675 Spurious timeout on console driver 

10699 Spurious timeout on parallel printer driver 

10700 Mismatch between loader version number and Operating System version 
number 

10701 OS exhausted its internal space during startup 

10702 Cannot make system process 

10703 Cannot kill pseudo-outer process 

10704 Cannot create driver 

10706 Cannot initialize floppy disk driver 

10707 Cannot initialize the File System volume 

10708 Hard disk mount table unreadable 
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10709 Cannot map screen data 

10710 Too many slot-based devices 

10724 Tne boot tracks do not know the right File System version 

10725 Either damaged File System or damaged contents 

10726 Boot device read failed 

10727 The OS will not fit into the available memory 

10728 SYSTEM.OS is missing 

10729 SYSTEM.CONFIG is corrupt 

10730 SYSTEM.OS is corrupt 

10731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

10732 SYSTEM.LLD is corrupt 

10733 Loader range error 

10734 Wrong driver is found. For instance^ storing a diskette loader on a ProFiie 

10735 SYSTEM.LLD Is missing 

10736 SYSTEM.UNPACK is missing 

10737 Unpack of SYSTEM.OS with SYSTEM.UNPACK failed 

11176 Found a pending write request for a pipe while in close_Object when it is 
called by the last writer of the pipe 

11177 Found a pending read request for a pipe while in Close_ObJect when it is 
called by the (only possible) reader of the pipe 

11178 Found a pending read request for a pipe while in Read_Data from tne pipe 
11180 Found a pending write request for a pipe while in write_Data to the pipe 
118XX Error xx from diskette ROM (See OS errors I8xx) 

11901 Call to Getspace or Relspace with a bad parameter, or free pool is bad 
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** defined for mounted or unmounted devices 
$ defined for mounted devices oniy 
Aii other fields are defined for mounted block-structured devices only. 



DEVICE_T, VOLUME_T: 

backup _volict 
blocksize 

* blockstructured 
boot_code 
boot_environ 
cluslersize 
copy 

copy_flag 
copy_threacl 
datasize 

* devt 

* dirjDath 
DTCC 
DTVB 
DTVC 
DTVS 
filecount 
freecount 
fs_overhead 

fs_size 
fsversion 

* iochannel 
label_size 

$ lockeddev 

macnineJD 

master 

master_copy_ID 
•" mounted 
$ mount jDending 

* name 

$ opencount 
overmount_stamp 
password 



ID of the volume of which this volume is a copy. 

Number of bytes in a block on this device. 

Flag set if this device is block-structured. 

Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set if this volume is a copy. 

Count of copy operations involving this volume. 

Number of data bytes in a page on this volume. 

Device type. 

Pathname of the volume/device. 

Date/time volume was created if it is a copy. 

Date/time volume was last backed-up. 

Date/time volume was created. 

Date/time volume was last scavenged. 

Count of files on this volume. 

Count of free pages on this volume. 

Number of pages on this volume required to store 

File System data structures. 

Number of pages on this volume. 

Version number of the File System under which 

this volume was initialized. 

Number of the expansion card channel through 

which this device is accessed. 

Size in bytes of the user-defined labels associated 

with objects on this volume. 

Reserved. 

Machine on which this volume was initialized. 

Reserved. 

Reserved. 

Flag set if a volume is mounted. 

Reserved. 

Name of this volume/device. 

Count of objects open on this volume/device. 

Reserved. 

Password of this volume. 
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$ prlvaiedev 
privileged 

$ remote 
result_scavenge 
scavenge_flag 

* slot_no 

$ unmount jDending 
voiid 
vol_left_mounted 

volname 

volnum 

vol_size 

wrlte_protected 



Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set Dy the scavenger if it has altered this 

volume in some way. 

Number of the expansion slot holding the card 

through which this device is accessed. 

Reserved. 

Unique identifier for this volume. 

Flag set if this volume was mounted during a 

system crash. 

Volume name. 

Volume number. 

Total number of blocks in the File System volume 

and boot area on this device. 

Reserved. 



OBJECT T: 



acmode 

dirjDath 

DTA 

DTB 

DTC 

DTM 

DTS 

eof 

etype 
file_closed_by_OS 

file_left_open 

file_scavenged 

fmark 
fs_overhead 

ftype 

fuid 

kswltch 

locked 

Ipsize 



Set of access modes associated with this refnum. 

Pathname of the directory containing this object. 

Date/time object was last accessed. 

Date/time object was last backed-up. 

Date/time object was created. 

Date/time object was last modified. 

Date/time object was last scavenged. 

Flag set if end of file has been encountered on 

this object (through the given refnum). 

Directory entry type. 

Flag set if this object was closed by the (iterating 

System. 

Flag set if this object was open during a system 

crash. 

Flag set by the Scavenger if this object has been 

altered in some way. 

Absolute byte to which the file mark points. 

Number of pages used by the File System to store 

control information about this object. 

Object type. 

Unique identifier for this object. 

Flag set when the object is killed. 

Reserved. 

Number of data bytes on a page. 
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machineJD Machine on which this ohject may be opened. 

master_file Flag set if this object is a master. 

name Entry name of this object. 

nreaders Number of processes with this object open for 

reading, 
nwriters Number of processes with this object open for 

writing, 
nusers Number of processes with this object open, 

private Flag set if this object is open for private access, 

protected Flag set if this object is protected, 

psize Physical size of this object in bytes, 

refnum Reference number for this object (argument to 

INFO). 
result_scavenge Reserved. 

safety _on value of the safety switch for this object, 

size Number of data bytes in this object (LEOF). 

system_type Reserved. 

user_type User-defined type field for this object. 

user_subtype User-defined subtype field for this object. 
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Please note that the topic references in this Index are by section numtjer. 

5.9.4 



accessing devices 1.3, 
ACTIVATE_PROCESS 3.8.6 
ALLOCATE 2.10.13 
Append access 2.10.8 
attribute 1.3, 2.10.5 



2.8 



CONVERT_TIME 

creating 

a data segment 4.7.1 
an event channel 5.8.1 
an object 2.10.1 
a process 3.3, 3.8.1 



baud rate 2.10.12.1 
binding 4.1 
BIND_DATASE6 4.7.12 
blocked process 1.4, 

3 (introduction), 3.8.5 
buffer 2.9, 2.10.12.1, 2.10.16, 

5.5, 5.8 



CARDS_EQUIPPED 6.1.1 
catalog 2.1, 2.5, 2.10.19 
changing file size 
clock 5.6 
clock system calls 
CLOSE_DATASEG 4.7. 
CLOSE_EVENT_CHN 5. 
CLOSE_OBJECT 2.10.9 
code segment 4.5 
communication between processes 
COMPACT 2.10.14, 2.10.15 
configuration 6 (introduction) 
configuration system calls 6.1 
controlling 

a device 2.10.12 

a process 3.4 



2.10.13-2.10.15 

5.9 
.4 
.8.4 
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data segment 

creating 4.7.1 

private 4.1, 4.4 

shared 1.7, 4.1, 4.3 

swapping 4.6 
Decode mnemonics 2.10.12 
Dcdata 2.10.12 
Dctype 2.10.12 
Dcversion 2.10.12 
DECLARE_EXCEP_HOL 5.7.1 
DELAYJIME 5.9.1 
deleting 

a process 3.8.2, 3.8.4 

an object 2.10.2 
device 2.3-2.7, 2.10.12 

accessing 1.3, 2.8 

control information 2.10,12 

mounting 1.3, 2.10.20 

names 2.1, 2.3, 2.10.12.1 

priority 2.3 

storage 2.4 
DEVICE_CONTROL 2.10.12 
directory 2 (introduction) 
DISABLE_EXCEP 5.7.2 
disk hard error codes 2.10.12.2 
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division by zero 5.2^ B 
Dread, Dwrite access 2.10.8 



FLUSH_OATASEG 4.7.5 
FLLISH_EVENT_CHN 5.8.7 
FLUSHJXCEP 5.7.6 
FS INFO fields E 



ENABLE_EXCEP 5.7.3 

end of file 2.7, 2.10.14, 2.10.15 

eof 2.10.5; see also end of file. 

error 

disk hard error codes 2.10.12.2 

error messages D 

soft error 2.10.12,1 

See also exception, 
event 1.6, 5.4, C 
event channel 1.7, 5.5, 5.8.1 
event management system calls 5.8 
event types C 
exception 1.6, 5.1-5.3, B 
exception handler 5.1, 5.3 
exception management system calls 

5.7 
exception names B 



father process 1.4, 3.6, 3.7, 

3.8.1, 3.8.2 
file 2 (introduction) 

access 2.8 

attributes 2.10.5-2.10.7 

changing size 2.10.13-2.10.15 

label 2.6^ 2.10.11 

marker 2.7, 2.10.15 

name 2.1, 2.10.1 

private 2.8 

shared 1.7, 2.8 
File System 1.3, 2 
File System calls 2.10 
FLUSH 2.10.16 



GET_C0NFI6_NAriE 6.1.2 
GET_NEXT_ENTRY 2.10.19 
GET_TIME 5.9.2 
GET_WORKING_DIR 2.10.18 
global access to files 2.8 
global event channel 5.5 
Global Refnum 2.8, 2.10.8 
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handshake 2.10.12.1 
hierarchy of processes 



3.2 



1 

INFO 2.10.6 
INF0_ADDRESS 4.7.9 
INFO_DATASEG 4.7.7 
INFO_EVENT_CHN 5.8.5 
INF0_EXCEP 5.7.4 
INF0_LDSN 4.7.8 
INF0_PR0CESS 3.8.3 
interface unit A 
interprocess communication 1.7, 
I/O 2 (introduction) 



2.9 



KILL_DATASEG 4.7.2 
KILL EVENT_CHN 5.8.2 
KILlIoBJECT 2.10.2 
KILL PROCESS 3,8.4 
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label, file 2.6, 2.10.11 
LDSN 4.2, 4.4, 4.7.8 
LECF. See end of file, 
local data segment 4.1 
local event channel 5.5 
logical data segment number 4.2, 

4.4, 4.7.8 
logical end of file. See end of 

file. 
LOOKUP 2.10.5 
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t1AKE_DATASEG 4.7.1 

MAKE_EVENT_CHN 5.8.1 

MAKE_FILE 2.10.1 

MAKE_PIPE 2.10.1 

MAKE_PROCESS 3.8.1 

memory management 1.5, 4.1-4.6 

memory management system calls 



4.7 



memory, parameter 6 (introduction) 

MEMJNFO 4.7.10 

mnemonics for Decode 2.10.12.1 

MOUNT 2.10.20 

mounting a device 1.3, 2.10.20 

MY ID 3.8.9 



-N- 



naming an object 
2.10.4 



2.1, 2,10.1, 



object 1.3 

creating 2.10.1 
deleting 2.10.2 
naming 2.1, 2.10.1 
renaming 2.10.4 



OPEN 2.10.8 
OPEN_DATASEG 4.7.3 
0PEN_EVENT_CHN 5.8.3 
OS interface A 
OSBOOTVOL 6.1.3 



page 2.4 

parameter memory 6 (introduction) 

parity 2.10.12.1 

pathname 1.3, 2.1, 2.2 

PEOF. See end of file. 

physical end of file. See end of 

file, 
pipe 1.7, 2.9. 2.10.1, 2.10.8 
priority of devices 2.3 
priority of processes 3.5, 3.8.7, 

3.8.8 
private access to files 2.8, 2.10.8 
private data segment 4.1, 4.4 
process 1.4, 3 

blocked 1.4, 3 (introduction), 
3.8.5 

creating 3.3, 3.8.1 

father 1.4, 3.6, 3.7, 3.8.1, 
3.8.2 

hierarchy 3.2 

priority 3.5, 3.8.7, 3.8.8 

queuing 3.5, 3.8.5-3.8.8 

scheduling 3.5, 3.8.5-3.8.8 

shell 1.4, 3.2 

son 1.4, 3.7, C 

starting 3.8.1, 3.8.6 

stopping 3.8.2, 3.8.4 

structure 3 . 1 

termination 1.4, 3.6, 5.2, B, C 
process system calls 3.8 
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queuing a process 3.5, 3.8.5-3.8.8 
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RENAME_ENTRY 2.10.4 
renaming an object 2.10.4 
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running a program 1.4, 1.9, 3.8.1, 
3.8.6 
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safety switch 
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SETACCESS_OATASEG 4.7. 
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SET_FILE_INFO 2.10.7 
SET_LOCAL_TI«E_DIFF 5.9.3 
SET_SAFETY 2.10.17 
SET_WORKING_DIR 2 . 10 . 18 
shared data segment 1.7, 4.1, 4.3 
shared file 1.7, 2.8 
shell process 1.4, 3.2 
SIGNAL_EXCEP 5.7.5 
SIZE_DATASEG 4.7.6 
soft error 2.10.12.1 
son process 1.4, 3.7, C 
sparing 2.10.12 

starting a process 3.8.1, 3.8.6 
stopping a process 3.8.2, 3.8.4 
storage device 2.4 
SUSPEND PROCESS 3.8.5 



swapping 4.6 
Syscall unit A 
system calls 

clock 5.9 

configuration 6 . 1 

event management 5.8 

exception management 5.7 

file 2.10 

memory management 4.7 
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system clock 5.6, 5.9 
system- defined exceptions 5.2, B 
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UNMOUNT 2.10.20 
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value out of bounds 5.2, B 
volume catalog 2.1, 2.5, 2.10.19 
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writing buffered data 2.10.16 
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